Usage alerting
Balance alerts
Detect when a customer’s prepaid‑credit balance is depleted, drops below a threshold, or recovers.
Alert types
| Alert type | Fires when the prepaid ledger… | Webhook event |
|---|---|---|
| Balance depleted | Transitions > 0 → 0 | customer.credit_balance_depleted |
| Balance dropped | Transitions ≥ configured threshold → below threshold | customer.credit_balance_dropped |
| Balance recovered | Transitions 0 → > 0 | customer.credit_balance_recovered |
Evaluation mechanics
| Trigger category | Specific events | Notes |
|---|---|---|
| Usage events | • Real‑time usage that draws down credits from the balance based on the billable metrics on the subscription. | See Usage‑based triggers for more information about expected latencies. |
| Credit blocks | • Activation (manual creation, creation due to an automatic allocation on the plan, or as the result of an automated top‑up) • Expiration or voiding | Block mutations may lag usage‑based triggers by a few minutes. |
| Alert config changes | • New balance alert created • Alert threshold added or removed | Forces immediate re‑evaluation so the new configuration is active within seconds. |
Fetching current alert state
Use the fetch‑alert endpoint to retrieve the serializedbalance_alert_status.The object lists each threshold alongside a boolean indicating whether it is currently in alert.
Practical considerations
- If the balance drops below and then quickly rises above a threshold, Orb may emit only the final (recovered) state. Rely on
balance_alert_statusserialized on the alert for the ground‑truth snapshot. - A depleted balance on the ledger can lead to immediate overage charges depending on plan configuration if usage continues. In order to resolve this, you can:
- Manually add and backdate a credit block will cover existing overages.
- Alternatively, enable top‑ups to automate this workflow; you can think of a top‑up as a material side effect of a balance alert. Note that top-ups also execute with the same tight SLAs as balance alerts, so will typically operate very quickly.