Verify Webhooks before Processing Their Payloads

A practical approach

Step 1

Preserve the raw bytes needed for signature verification and keep signing secrets on the server. Apply timestamp or replay checks when the provider’s scheme supports them.

Step 2

Store a unique event ID before performing side effects. Duplicate delivery should not create duplicate business actions.

Step 3

Acknowledge according to the provider’s contract and move slow work to a queue where appropriate. Handle out-of-order events using business state, not arrival order alone.

Worked example

A registration provider sends the same confirmation event twice after a temporary timeout. The receiver recognizes the event ID and returns the recorded outcome instead of sending a second welcome message or creating another enrollment.

A mistake to avoid

Parsing and reserializing JSON before signature verification can change the bytes being checked. Also avoid treating any incoming payload that contains a familiar event name as authentic.

Try it yourself

In a test environment, send a valid event, a duplicate, an altered body and an older event arriving late. Confirm the expected acceptance, rejection and state transition for each.

Your implementation checklist

• Authenticity is verified before side effects.
• Raw-body requirements are preserved.
• Duplicate events are harmless.
• Out-of-order delivery has a defined policy.