Stripe webhooks arriving out of order: handling it safely
Short answer: Stripe doesn't guarantee that webhook events arrive in the order they happened, and the same event can arrive more than once. If your app updates order or subscription status straight from each event's payload, an older event can overwrite a newer one. Record event IDs to skip duplicates, acknowledge quickly and process in the background, and treat each event as a prompt to fetch the object's current state from the API, or compare timestamps and allowed status transitions, before changing anything.
What goes wrong
A typical first webhook handler does this: receive invoice.paid, mark the order as paid; receive invoice.payment_failed, mark it as failed. It works in testing because events arrive one at a time, in order.
In production, things are messier. Stripe's webhook documentation states that it doesn't guarantee delivery of events in the order they're generated. It gives the example of a new subscription, which can produce customer.subscription.created, invoice.created, invoice.paid and charge.created events, and notes your endpoint shouldn't expect them in that sequence. Retries after a timeout or error make it more likely an older event lands after a newer one.
The result can be an order shown as "payment failed" after the customer successfully paid on a retry, or a subscription marked active after it was cancelled. These bugs are intermittent, hard to reproduce and very confusing for support staff.
Rule 1: deduplicate by event ID
Stripe's documentation also notes that endpoints might occasionally receive the same event more than once, and recommends guarding against this by logging the event IDs you've processed and skipping ones you've already handled.
In practice:
- Store each processed event ID in a table with a unique constraint.
- Insert the ID in the same database transaction as the changes the event causes.
- If the insert fails because the ID exists, stop: it's a duplicate.
Doing both in one transaction means a crash halfway through doesn't leave the event marked as processed while the change was never saved.
Rule 2: acknowledge fast, work later
Stripe's guidance is to return a successful 2xx response quickly, before complex logic that might time out. Slow handlers cause timeouts, timeouts cause retries, and retries make ordering problems worse.
A dependable pattern:
- Verify the webhook signature.
- Save the raw event, or its ID and type, to a queue or table.
- Return 200 immediately.
- Process the event in a background job.
The background job can retry on its own schedule and in a controlled order without holding up Stripe.
Rule 3: fetch the current state
The most reliable way to handle ordering is to stop trusting the event's snapshot as the final word. When you receive an event about an invoice, subscription or payment, fetch that object from the Stripe API and apply its current status. Stripe's docs mention retrieving objects through the API to fill in anything missing.
That way, it doesn't matter which event arrives first: whichever one you process, you end up with the latest truth. An old invoice.payment_failed arriving late simply triggers a fetch that shows the invoice is now paid.
The trade-off is extra API calls. For most small business volumes that's fine; check Stripe's API rate limits for your account if you process many events in bursts.
Rule 4: guard transitions in your own data
Even with fetching, protect your own records with rules about what can change:
- Allowed transitions. An order can go from
pendingtopaid, but not frompaidback topendingbecause of a stale event. Encode that as a check before updating. - Timestamps. Each Stripe event has a
createdtime. Store the timestamp of the last event applied to each object and ignore events older than it, if you rely on payloads rather than fetching. - Terminal states. Once refunded or cancelled, require an explicit newer signal to change.
These rules also protect you from bugs in your own code, not just from Stripe's delivery order.
Rule 5: only handle what you need
Subscribe your endpoint to the event types your app actually uses. Fewer event types mean fewer opportunities for confusing interactions, and less load. Review the list when you add features.
Recovering after an outage
If your endpoint was down, Stripe retries for a while, but you may also want to process missed events yourself. Stripe's guide to processing undelivered events describes listing events through the API and processing them oldest first. It notes that the API only returns events from the last 30 days, and warns that your recovery script and Stripe's automatic retries may overlap, so deduplication matters here too.
Test the awkward cases
Use test mode and the Stripe CLI to send events, then deliberately:
- Send the same event twice.
- Send a "failed" event after a "paid" event for the same invoice.
- Make your handler time out once, then succeed.
- Process events while the background worker is stopped, then start it.
Your records should end in the right state every time.
A worked example
Picture a hypothetical Montreal language-school platform selling monthly class subscriptions. Some students were locked out despite paying, because a late invoice.payment_failed from an earlier attempt overwrote the invoice.paid from a successful retry. The team added an event-ID table, moved processing to a background job after a quick 200 response, fetched the latest subscription and invoice from the API in each job, and blocked transitions from active back to past_due unless the fetched status said so. Lock-out complaints stopped.
FAQ
Does this only apply to Stripe?
No. Many payment and SaaS providers make similar delivery guarantees. Check each provider's documentation.
Should I verify signatures before deduplicating?
Yes. Verify first, so forged requests never touch your data.
Can I rely on event order within one object?
Don't. Design as though any order is possible.
Is fetching from the API always necessary?
Not always. Timestamps and transition rules can be enough for simple cases, but fetching is the safest option.
If your app's payment statuses sometimes go wrong after webhooks, show us how your handler works.