Webhook arrival order is not necessarily business-event order. Protect current state from older deliveries by using the source system’s supported versions, authoritative lookups, and explicit transition rules.
Out-of-order events need domain semantics
An out-of-order event arrives after a later event for the same resource. Network delays, retries, and parallel processing can produce this pattern. Processing every payload as the newest truth can move a record backward.
In a proposed integration, distinguish receipt time, source event time, resource version, and processing attempt. Use a reliable source version when available. A timestamp alone may be insufficient when clock precision or event-generation behaviour is unclear.
Do not invent ordering guarantees that the provider does not document. Stripe’s webhook guidance discusses event-ordering considerations for its service; verify the actual provider’s contract before designing the projection strategy.
Exercise a fictional request lifecycle
A source emits “request assigned” and then “request closed.” The close event arrives first. When the delayed assignment arrives, the local dashboard should not reopen the request merely because that delivery is newest by receipt time.
One approach uses supported resource versions to reject stale updates. Another treats the event as a signal to fetch the authoritative current resource. The latter adds reads and may not recover historical transitions, so choose according to the required semantics.
| Event sequence | Required invariant |
|---|---|
| Close arrives before assignment | Final state stays consistent with authority |
| Same event delivered twice | No duplicate side effect |
| Two workers process one resource | Concurrency rule preserves current state |
| Old event after local staff edit | Apply the defined ownership and conflict policy |
| Missing intermediate event | Reconcile without inventing history |
Retain a receipt ledger showing what arrived and how it was handled. Ignoring a stale event can be correct, but the decision should remain diagnosable.
Separate projections from external effects
Updating a dashboard projection is different from sending an email or creating an appointment. A late event may be harmless to ignore for current state but still require careful handling of a previously unperformed business effect. Define those rules explicitly.
Serialising work per resource can simplify ordering but reduce throughput and introduce blocked queues. Authoritative refreshes can improve current accuracy while adding rate-limit pressure. Test the tradeoff with realistic event bursts and recovery sequences.
This ordering design is proposed. The voice platform case study establishes related integration experience. See stale conversation-state controls for a similar freshness boundary.
Event ordering FAQ
Can receipt timestamps define the latest business state?
Not reliably. Receipt order can differ from source order.
Should every old event be discarded?
Decide by domain effect. Current projections and one-time side effects may need different handling.
What if the provider has no usable version?
Use its supported reconciliation mechanisms and explicit conflict rules, while documenting the remaining limits.