Billing Webhooks: Handle Duplicate and Out-of-Order Messages

Billing webhook processing: what to decide

An invoice-paid message arrives twice. A naive handler grants credits twice. Another account receives a newer subscription update before an older one. Both are normal conditions a robust integration should be prepared to handle.

Use the provider’s documented verification mechanism and track processed events. When order matters, reconcile against authoritative object state instead of blindly applying arrival order. Keep side effects idempotent and avoid trusting an unsigned payload.

How this works in practice

A paid invoice grants 1,000 credits. Processing the same provider event a second time should return the existing result without another grant. A separate genuinely new payment event needs its own review and identity.

What can go wrong

Acknowledging before durable recording risks losing a message; doing extensive work before acknowledgement can cause repeated delivery. Choose a durable handoff and monitor failures in the background processing path.

Questions for your team

• Verify signatures as documented.
• Persist event identity and processing outcome.
• Make grants and state changes idempotent.
• Reconcile uncertain state with the provider.