{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "balance.low",
"created": 123,
"data": {
"object": {
"environment_id": "<string>",
"available": 123,
"held": 123,
"currency": "USD"
}
}
}Event types
balance.low
Sent when an environment’s available balance crosses below the low-balance threshold.
WEBHOOK
balance.low
{
"id": "evt_8aZqRm4yT3vK7pNxJ2bH9c",
"type": "balance.low",
"created": 123,
"data": {
"object": {
"environment_id": "<string>",
"available": 123,
"held": 123,
"currency": "USD"
}
}
}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 mintfax’s low-balance threshold. The threshold is platform-controlled and applies to every account. 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 newbalance.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-idprevents 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 credit pool and operates from the same threshold signal without requiring webhook handling.
Authorizations
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.
Event identifier (evt_-prefixed). Stable across retry attempts.
Example:
"evt_8aZqRm4yT3vK7pNxJ2bH9c"
Event type. Always balance.low for this delivery.
Available options:
balance.low Unix epoch seconds when the event was generated.
Show child attributes
Show child attributes
Response
2XX
Acknowledged. mintfax treats any 2xx response as a successful delivery.
Last modified on October 1, 2026