Usage-based subscriptions use subscription and invoice webhooks to communicate lifecycle and payment outcomes.
XPay doesn't send a webhook for every meter event. Use the synchronous meter-event response for submission handling and the invoice webhook for billing reconciliation.
Relevant events
Reconcile the invoice
When handling an invoice_payment event for a usage-based subscription:
- Match the invoice and subscription IDs.
- Store the invoice state and payment attempt result.
- Read
pricing_model_breakdownfor each pricing model and meter contribution. - Compare the result with the merchant's submitted usage records.
- Update customer access from the subscription state.
Process billing events
Refunds don't change the subscription state. After
REFUND_NOTIFICATION, keep the subscription and refund records separate unless another billing action changes the subscription.Use Integrate XPay webhooks for signature verification and delivery handling. For usage-based billing, route by event type, keep invoice and subscription states separate, and retrieve the current billing object when an event doesn't contain enough information for the merchant's decision.
The stage environment sends these webhooks automatically. To resend a notification for testing, use the manual webhook action on the relevant subscription or transaction in the merchant portal.