chargeback webhook events arrived out of order: how to fix

TL;DR

Webhook providers do not guarantee event order, so your state machine must tolerate an update arriving before its creation event. Compare each event's created timestamp against your stored state and apply only events newer than what you already have.

chargeback webhook events arrived out of order: how to fix

Use this when

• Event sequences contradict each other or states flip backwards.
• A dispute shows won, then open, then won again.
• Your state machine throws on impossible transitions.

Not for this skill when

• The same event arrives twice. That is duplication.
• Events never arrive. That is delivery.

Steps

1. Store the provider's created timestamp (or sequence id) with every dispute state you keep. Verify: each stored state carries the timestamp of the event that set it.
2. On each incoming event, compare its timestamp to the stored one and ignore the event if it is older. Verify: a late-arriving older event changes nothing.
3. Apply the event if it is newer, even if the transition looks odd. Verify: the stored state always reflects the newest event seen.
4. Make every transition idempotent so replaying the newest event is harmless. Verify: applying the same event twice leaves one state row.
5. Add a periodic reconciliation against the provider's dispute API to catch anything the event stream garbled. Verify: the reconciler would have caught your last ordering incident.

Variant phrasings

webhook events out of order chargeback

Common search order.

dispute state flipped backwards webhook

Symptom wording.

chargeback event ordering problem

General phrasing.

Compatibility: Stripe, Adyen, Braintree, and similar webhook providers. None promise ordered delivery; all provide a created timestamp or equivalent.

Why it happens

Webhooks travel over independent HTTP requests through queues with retries. A retried older event can easily land after a newer one, and two workers can process them in arrival order. The provider sees one timeline; your server sees the network's timeline.

Edge cases / pitfalls

• Do not sort by arrival time. Arrival order is the thing that is wrong.
• Clock skew between you and the provider is usually small, but compare with a tolerance of a few seconds.
• Ignoring stale events is correct even when the stale event looks alarming. Newest wins, always.
• Reconciliation is not optional. Ordering bugs are silent until they are expensive.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst6qWtPqMpyU3n7yoL6Q0rw