Skip to main content
WEBHOOK
balance.low
{
  "id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
  "created": 123,
  "data": {
    "object": {
      "environment_id": "<string>",
      "available": 123,
      "held": 123,
      "currency": "USD"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

This event is part of the published catalog but is not yet emitted by mintfax. The schema on this page is the target so you can build against it now. Subscribing to balance.low today will not return an error, but no deliveries will arrive until the producer ships.

​
When it will fire

When the available balance for an environment drops below the configured low-balance threshold. The threshold is set per environment in the dashboard. The event fires on the transition - it does not refire on every fax billed against a balance that is already below the threshold. If the balance is topped up and then crosses the threshold again, a new balance.low is fired.

​
What your handler should do

  • Trigger your top-up workflow. Whether that is manual, an Approval queue, or an automated charge against your billing source is up to you.
  • Persist the event ID. If your top-up workflow is asynchronous, deduplicating on webhook-id prevents a webhook redelivery from triggering a duplicate top-up.
  • Consider using auto-top-up instead of handling this event manually. Auto-top-up is configured per environment and operates from the same threshold signal without requiring webhook handling.

Authorizations

​
Authorization
string
header
required

API key as Bearer token. Use an account key (mfx_acct_...) for /account/* endpoints, and an environment key (mfx_test_... for sandbox, mfx_live_... for live) for /environment/*, /faxes, /webhooks, and /events.

Body

application/json

Event delivery to your subscribed webhook endpoint.

Webhook delivery for balance.low.

​
id
string
required

Event identifier (evt_-prefixed). Stable across retry attempts.

Example:

"evt_8aZqRm4yT3vK7pNxJ2bH9c"

​
type
enum<string>
required

Event type. Always balance.low for this delivery.

Available options:
balance.low
​
created
integer
required

Unix epoch seconds when the event was generated.

​
data
object
required

Response

2XX

Acknowledged. mintfax treats any 2xx response as a successful delivery.

Last modified on May 14, 2026