Webhook Event Ordering Problems

Why webhook event ordering breaks

• network latency varies between requests
• providers retry only some failed events
• background workers process jobs in parallel
• distributed systems do not guarantee strict ordering
• downstream services may complete work at different times

A later event may arrive first simply because the earlier event encountered a retry or slower route.

A common real-world example

subscription.updated
subscription.created

Suppose your application expects subscription.created to run first and insert a local record. If subscription.updated arrives before that happens, the handler may fail because the subscription does not exist yet.

In billing systems, similar problems appear with:

• invoice paid before local subscription row exists
• refund event before payment sync finishes
• plan change before initial provisioning completes

Why timestamps are not enough

A common first idea is to compare timestamps and ignore older events.

That helps sometimes, but it is not a complete solution.

Problems with timestamp-only logic:

• different event types may not be directly comparable
• clock differences can create ambiguity
• an older event may still contain a required state transition
• timestamps do not tell you whether the current resource state is already correct

Ordering bugs are not only about time. They are about state correctness.

Safer design: reconcile against current state

In many systems, the safest approach is not “apply events in arrival order.” It is “reconcile local state with the provider’s current truth.”

For example, if a subscription update event arrives before creation appears locally, the handler can fetch the latest provider state and build the local record from that instead of failing blindly.

This turns event processing into a state-reconciliation workflow rather than a fragile sequence dependency.

Sequence numbers and versions

Some systems solve ordering by attaching explicit versions or sequence numbers to resources.

If your payload includes a version field, the handler can ignore stale updates:

if ($incomingVersion < $currentVersion) {
    return;
}

This works best when:

• the provider guarantees monotonic versioning
• the field is resource-specific, not global
• your application stores the latest processed version

Without those guarantees, version comparison can be misleading.

Buffering vs fetching canonical state

There are two common recovery strategies when ordering is broken.

1. Buffer and retry later

If a dependent resource is missing, temporarily defer the event and try again after a short delay.

2. Fetch canonical state immediately

Query the provider API and reconcile local data from the current source of truth.

Buffering is useful when the missing event is likely to arrive soon. Fetching current state is safer when strict ordering cannot be trusted at all.

Idempotency still matters

Ordering problems and duplicate delivery problems often appear together.

A retry of an older event may arrive after a newer event was already processed. That means handlers must be both:

• idempotent
• state-aware

If you have not already implemented duplicate protection, see idempotent webhooks in Laravel .

Architecture patterns that help

• store webhook events before processing
• process asynchronously through queues
• persist resource version or last-known state
• use reconciliation jobs for drift repair
• avoid assuming webhook order equals business order

These patterns become even more important in distributed systems. See why webhooks break in microservices and webhook processing architecture .