SaaS Billing Webhooks: Preventing Duplicate and Missed Actions
Design reliable SaaS billing webhooks with signature verification, event deduplication, state reconciliation, and safe retries for subscription changes.
By RZoraTech Team, Engineering & Product · · 3 min read
Billing webhooks connect a payment provider's events to your product's account state. They can be delivered more than once, arrive out of order, or be delayed by network problems. Reliable billing treats those behaviours as normal operating conditions. Build event verification, deduplication, and reconciliation before a subscription affects customer access.
Verify and store the event safely
Verify the provider signature using the original request body and the correct endpoint secret. Parsing or modifying the payload before verification can break the signature check. Distinguish test and live environments, and reject invalid events before doing business work.
Store a durable event identifier and processing status. Acknowledge valid delivery promptly once the work is safely accepted, then process expensive steps asynchronously when needed. Do not return success before persistence if a process crash would silently lose the event. The exact implementation should follow your provider's current documentation.
Make state changes repeatable
A duplicate delivery should not create a second invoice record, grant credits twice, or send repeated notifications. Use uniqueness constraints and transactional changes around the business action. An in-memory list of processed events is insufficient across restarts and multiple workers.
Avoid assuming event order. When an old update arrives after a newer one, reconcile against the authoritative subscription state or use a carefully designed versioning strategy. Map billing status to entitlements explicitly, including trial, overdue, cancellation, and grace-period behaviour. A raw payment event is not always the same as a product access decision.
Provide an operational recovery path
Record failed events and make retries observable. Give the operations team a way to replay processing safely without bypassing deduplication. Periodically reconcile local subscription records with provider state to detect missed or incomplete updates.
Test duplicate deliveries, out-of-order events, invalid signatures, database failures, and worker crashes. Keep billing secrets and sensitive payload fields out of ordinary logs. Define who handles discrepancies and how customers are supported when payment and access disagree. Reliable billing is a workflow spanning engineering, product, and operations.
What to follow before development
- Verify signatures against the raw request body.
- Persist event IDs with database uniqueness constraints.
- Make entitlement changes transactional and idempotent.
- Test out-of-order delivery and schedule reconciliation.
A practical example
A subscription renewal event arrives twice after a delivery timeout. The first transaction records the event and adds the monthly allowance. The second sees the same unique event ID and performs no additional credit change. A reconciliation job later checks provider state, catching any account whose billing status and entitlements diverged.
Sources and further reading
Plan your next step
Turn your priorities into a scoped engineering plan with our web app development team. For a related implementation guide, read observability.
Frequently asked questions
- Can I assume a webhook arrives exactly once?
- No. Design for repeated deliveries and provider-specific ordering behaviour. Durable deduplication and reconciliation help keep local billing state consistent.