Usage alert webhook behavior at billing period reset

Usage alerts in Lago do not fire a webhook when the billing period resets at a customer's anniversary. The threshold counters reset silently when the new period begins, and a new alert.triggered webhook only fires if the customer crosses the threshold again in the new period. There is also no downward webhook when usage drops below a threshold.

How it works

Usage alerts created via the alerts API fire an alert.triggered webhook when a customer's usage crosses a configured threshold. This webhook is distinct from subscription.usage_threshold_reached, which is used only for progressive billing thresholds, not for alerts. Using the wrong webhook type in a flow is an easy mistake since both are usage-related.

For current usage alerts, the threshold counter resets to zero at the customer's billing anniversary when the new period begins. No webhook fires on this reset. If the customer crosses the threshold again in the new period, alert.triggered fires again. For lifetime usage alerts, the counter never resets and only fires once per threshold unless the threshold is configured as recurring.

The recurring: true option on a threshold is not related to billing period resets. It controls whether Lago re-fires the alert at regular intervals once usage has passed all fixed thresholds, which is useful for catching usage that keeps climbing past the last defined limit.

Threshold codes (soft, hard, hard_limit in the docs) are illustrative examples. They are user-defined free-text strings you set when creating the alert, and they appear in the webhook payload to identify which threshold fired.

How to implement

To detect when a billing period resets and re-enable a feature that was gated on a usage limit, listen for invoice.created filtered on invoice_type = subscription. This fires at the start of each new billing period. If you have a grace period configured, invoice.created fires after the grace period expires; invoice.drafted fires earlier if you need the earliest possible signal. Listen for both and deduplicate on invoice ID to act on whichever comes first.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.