Home/REST Track/Webhook Signatures, Replay Defense & Ordering

Webhook Signatures, Replay Defense & Ordering

Verify webhook authenticity, reject replays, and survive out-of-order carrier events.

Trust the Raw Body, Not the Parsed Object

Webhook signature verification usually depends on the exact raw request body plus a shared secret. If your framework parses and rewrites the payload before verification, a valid event can fail signature validation or, worse, an invalid event can slip through if you verify the wrong bytes.

Replay and Ordering Are Separate Problems

A replay attack resends the same event. Out-of-order delivery sends valid but differently timed events in the wrong sequence. You need an event ID ledger for replay defense and timestamp or sequence handling for ordering. One control does not solve the other.
Carrier Reality

A carrier can deliver 'delivered' before 'out for delivery' because separate internal systems publish the updates. If you trust arrival order, your status model regresses in public-facing tracking.

Acknowledge Fast, Observe Deeply

The receiver should verify, persist, and acknowledge quickly. Heavy downstream work belongs in asynchronous workers. Pair that with event-level logging so you can reconstruct replay, ordering, and deduplication behavior during an incident.

Practice Drills

When investigating webhook replay or ordering incidents, log the carrier ID, your internal ID, the signature-verification , the event , and the queue or worker that handled it.

What should a webhook receiver do first when it gets a carrier tracking update?