Webhook Events

Balance empty event

Balance billing only. The balance reached $0 and no auto top-up covered it (auto top-up off, the card declined, or the monthly limit reached), so new pay-per-use (SMS, calls, numbers, X and the rest) answers 402 with code until the balance is funded.

When it fires

Once per time the balance runs out, within about a minute of the usage that emptied it. Funding the balance and running out again fires it again.

Who receives it

The billing owner's endpoints, like balance.low. Restricted keys need the money resource group.

How to act

Send the user to fundingUrl, or, for usage_limit_reached, raise monthlyLimitCents with PATCH /v1/balance/auto-recharge.

postWebhookbalance.empty

Payload

idstring required

Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.

testboolean

Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.

event'balance.empty' required

code'insufficient_balance' | 'usage_limit_reached' required

The 402 code pay-per-use calls get until the balance is funded. usage_limit_reached when the auto top-up monthly limit is what keeps it at $0.

fundingUrlstring uri required

Dashboard link that opens the Add funds drawer in Billing.

timestampstring date-time required

UTC time at which Zernio generated this event. Retries and redeliveries keep the original value.

Response

Webhook received successfully

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.