A handler that works in testing can break in production because two events arrive in a different order than they happened. A customer pays, and the invoice.paid handler runs before anything has recorded the subscription it belongs to. The row doesn't exist yet, the update matches nothing, and access never unlocks.
Stripe documents this behavior. This post covers what the docs say about ordering, what not to use as an ordering key, and a handler pattern that works whatever order events arrive in. Every claim links to the doc it comes from (see Sources at the end).
What Stripe says about ordering
From the webhooks docs: "Stripe doesn't guarantee the delivery of events in the order that they're generated."
The docs give an example. Creating a subscription might generate these events:
customer.subscription.createdinvoice.createdinvoice.paid-
charge.created(if there's a charge)
The instruction that follows: "Make sure that your event destination isn't dependent on receiving events in a specific order."
Don't sort by created
It's tempting to store each event's created value and ignore anything older than the last one seen. The docs warn against it: "Snapshot events record created in seconds, so distinct events can share a timestamp. Don't use created to determine event order or whether you've already processed an event."
Two events from the same second can't be put in order by that field, and it isn't a duplicate check either. For duplicates, Stripe says: "Track event IDs to identify duplicate deliveries instead."
Fetch the object instead of trusting the sequence
Stripe's suggested way out: "You can also use the API to retrieve any missing objects. For example, you can retrieve the invoice, charge, and subscription objects with the information from invoice.paid if you receive this event first."
So treat an event as a signal that something changed, and read the current state from the API when you need it. The docs say the same for snapshot handlers: "You can also retrieve the API resource from the Stripe API to access the latest and up-to-date object definition."
// Verify the signature first (raw body, per-endpoint whsec_), then:
if (await alreadyProcessed(event.id)) return res.sendStatus(200);
switch (event.type) {
case 'invoice.paid': {
const invoice = event.data.object;
// Don't assume the subscription row exists yet.
const sub = await stripe.subscriptions.retrieve(invoice.subscription);
await upsertAccess(sub); // insert-or-update from the current Stripe state
break;
}
}
await markProcessed(event.id);
res.sendStatus(200);
(invoice.subscription is illustrative; check the field name for the API version your account uses.)
The key choices: the write is an upsert built from the retrieved object, so it doesn't matter which event arrives first, and the event ID is recorded so a repeat does nothing.
Checklist
- [ ] No handler assumes another event ran first
- [ ] Writes are upserts built from the current object, not "update where exists"
- [ ] Event IDs are logged to skip duplicates;
createdis not used for ordering or dedup - [ ] Missing related objects are retrieved from the API
- [ ] The handler returns a
2xxquickly, before slow work (Stripe: "Quickly returns a successful status code (2xx) before any complex logic that might cause a timeout")
Out-of-order delivery is one of several ways a webhook integration can misbehave without anyone noticing. WebhookProof's free checker sends 3 harmless test requests to a webhook URL you own and reports whether Stripe can reach it and whether unsigned requests are rejected. The full guide is here: Stripe webhook events out of order
WebhookProof is an independent tool, not affiliated with Stripe, Inc. Quotes are from the linked documentation as read on 2026-11-16.
Sources
- Stripe, Receive Stripe events in your webhook endpoint (Event ordering, handle duplicate events, snapshot event handler, quickly return a 2xx response): https://docs.stripe.com/webhooks
Top comments (0)