Webhook Signature Verification and Replay Checks

Verify bytes before interpreting the event

Read the provider's exact signed-message construction. Some schemes sign the body together with header data; others sign the raw body alone. Parsing JSON and serializing it again can change whitespace or ordering and therefore the signed bytes. Capture the raw payload through the supported framework path before applying business logic.

Stripe documents verification with the raw request body and its signature header. Sumsub documents HMAC verification using raw bytes and its digest-algorithm header. These are different integration contracts. Prefer supported libraries where available and reject unsupported algorithms rather than silently trying whichever digest produces a match.

Separate authenticity, freshness and uniqueness

A valid signature answers whether the message matches the signed content under the selected key. It does not prove that the message is new to your system or that its requested business transition is allowed. Stripe's scheme includes a signed delivery timestamp and documents a tolerance check; do not assume the same header or tolerance exists for every vendor.

Use the provider's documented time field for freshness, with a monitored clock. The business event's creation time can be older than a legitimate retried delivery, so substituting it for a signed delivery timestamp can reject valid recovery traffic. Independently record event identity and processing outcome so a fresh, authentic retry does not repeat an economic action.

Test failure paths without weakening verification

Test the correct secret, wrong secret, one-byte body change, missing signature, unsupported algorithm, stale signed timestamp where applicable and legitimate repeated delivery. During secret rotation, accept only the documented set of active secrets and record when the old one is retired.

Do not make verification optional in production merely because a test request lacks a header. Maintain a separate controlled test path or use the provider's signed test events. Return and retry behavior should follow the provider's contract, while internal acceptance should be durable enough for later processing. A verified payment event still does not establish merchant eligibility or final settlement; those decisions require their own evidence.

Example: valid signature, repeated action

A fictional event E-92 is verified and stored, then causes one internal update. The provider retries E-92 because its earlier delivery acknowledgment was lost. The second signature is valid, but the stored event identity shows processing is complete. The handler records the repeated receipt and acknowledges it according to the provider contract without posting another credit. In a separate test, changing an amount digit makes signature verification fail before any update is considered.