Handle Webhooks That Arrive Out of Order

Do not assume webhook arrival order matches the order in which the underlying changes occurred. Design the consumer around the object's valid state transitions or retrieve its authoritative current state when the provider's API and event model support that approach.

Separate stale events from duplicate events

A duplicate repeats an event identity. An out-of-order event can be a different legitimate event delivered later than a newer one. Deduplicating event IDs does not solve stale updates.

Stripe's webhook guidance states that event ordering is not guaranteed. Verify the delivery and payload semantics of your own provider before using a timestamp or version as an ordering rule.

Store the event identifier, object identifier, event type, occurrence time and receipt time separately. They answer different questions.

Write the allowed state transitions

For an illustrative document-processing job, the states might be queued, processing, completed and failed. A late processing event should not overwrite a verified completed state merely because it arrived last.

Current state	Incoming event	Decision to evaluate
Processing	Completed	Apply verified completion
Completed	Earlier processing	Preserve completion
Failed	New retry started	Identify a new attempt
Unknown	Completion	Retrieve or reconstruct required state

This table is a design example. Your domain may legitimately allow reopening or reversal, so do not impose a universal monotonic order.

Choose a reconciliation strategy

If events provide a reliable object version, compare versions according to the provider's contract. If they are notifications to fetch current state, retrieve that state and update your local representation carefully.

If each event represents an immutable action, process the action once rather than simply replacing a current-state record.

Account for races between reconciliation workers. A read of current state followed by a delayed write can still overwrite a newer local update unless concurrency is controlled.

Preserve the event history

Keep enough sanitized history to explain why an event was ignored, applied or deferred. “Old event” should be a traceable decision, not a swallowed exception.

If prerequisite data is missing, place the event in a bounded retry or reconciliation queue. Do not assume that sleeping for a fixed interval makes every missing predecessor arrive.

Test shuffled sequences

Create a fixture sequence, then replay it in normal order, reverse order and with duplicates. Include a retry attempt and a legitimate reversal if your business process allows them.

The expected final state should be defined before running the test. Also verify the number of external side effects.

For an AI agent application, an older status event should not restart completed work. Keep this lifecycle logic in the application rather than asking the model to infer event chronology.

Related troubleshooting

• Handle Duplicate Webhook Events
• Scheduled Job Ran Twice: Prevent Duplicate Work

This guide draws on the linked documentation. Examples are illustrative unless explicitly identified as measured results.