Usage webhooks
React to usage thresholds and billing outcomes without double-processing events.
Separate metering from payment
Usage events record consumption. Threshold notifications describe progress or limits. Invoice and payment events describe billing and payment outcomes. Do not fulfil an order or mark an invoice paid merely because usage was ingested or a threshold was reached.
Subscribe to the event types listed in the event catalogue, including usage.threshold.reached where configured. Set thresholds on the meter and test crossing them with a small staging dataset. Treat a threshold as a notification unless your application separately enforces a limit.
Receiver workflow
- Verify the signature against the raw body.
- Durably accept the event with a merchant-scoped event ID before responding.
- Retrieve current meter/customer/subscription state with a server credential.
- Apply the business action once and record its outcome.
- Handle duplicate and out-of-order delivery without sending repeated customer messages.
Use the receiving guide and delivery/retry rules. CLI trigger fixtures test your receiver; they do not prove that a real meter emitted an event or that a provider collected funds.