Create alerting rules
Orb lets you set alerts, which can be configured through our API or app, that trigger webhooks when active subscriptions hit specific usage and cost thresholds. These alerts can be used to notify internal teams of anomalous activity, power an overage notification workflow to customers, or prevent excessive use of a product feature.
All alerts in Orb support a multi-threshold configuration, allowing you to set incremental alerting values. By default, alerting thresholds follow a monthly evaluation cadence and reset each billing period.
In cases where two or more thresholds are crossed in quick succession, Orb ensures that a single notification for the greater of the thresholds is delivered to your webhook handler.
Types of alerts
Alerts on usage, cost, and credit balance are evaluated several times a day, but the latency guarantee will be a function of your workload. This can be reduced with provisioning for customers on Growth and Enterprise plans.
| Alert type | Description | Webhook event type |
|---|---|---|
| Usage | These alerts are tied to a specific billable metric. The alert is triggered when usage exceeds a pre-specified numeric threshold in the quantity units of the metric. | subscription.usage_exceeded |
| Cost | Triggered when the upcoming invoice for the subscription exceeds a monetary threshold. Note that this accounts for minimums and fixed fees. The alert is evaluated over the full billing period. | subscription.cost_exceeded |
| Balance | Triggered when the ledger is depleted to a configured threshold. | customer.credit_balance_depleted, customer.credit_balance_dropped |
Managing alert states
Alerts are often tied to a specific plan or type of subscription. Accordingly, Orb allows you to configure alerts on the plan itself and automatically propagates them to all subscriptions of that plan. This allows you to quickly add an alert to an existing plan without having to run a migration over existing subscriptions. Similarly, when an alert is disabled, this change applies to all subscriptions.
It's often useful to set ad hoc alerts for specific customers (especially when dealing with Enterprise contracts), so alerts can also be managed at the individual subscription level. Orb's subscription card allows you to view alerts inherited from the plan and change them for the specific subscription instance. With this workflow, you can create alerts that correspond to a customer's usage patterns, even if they differ from other subscriptions to the same plan.
Viewing triggered alerts
Each subscription card on the customer page in Orb shows which alerts have been triggered during the current billing period, and the time at which the threshold was exceeded.
