Alert types

Alert typeFires when the prepaid ledger…Webhook event
Balance depletedTransitions > 0 → 0customer.credit_balance_depleted
Balance droppedTransitions ≥ configured threshold → below thresholdcustomer.credit_balance_dropped
Balance recoveredTransitions 0 → > 0customer.credit_balance_recovered

Evaluation mechanics

Trigger categorySpecific eventsNotes
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 serialized balance_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_status serialized 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.