Webhook signature failure checklist before rotating secrets

Before rotating webhook secrets, check raw body handling, timestamp tolerance, route selection, and secret version against the provider delivery record.

Rotating the secret too early can hide the original bug. A signature failure may come from verifying parsed JSON instead of the raw body, reading the request stream twice, using the wrong route middleware, accepting a timestamp outside the provider window, or deploying one environment with an old secret and another with a new one. If the team changes the secret first, the incident gains a second variable.

Build a compact packet. Record provider event id, delivery attempt, timestamp header, signature header presence, receiver trace id, endpoint path, environment, secret version label, verification result, and handler outcome. Keep the raw body shape but remove customer identifiers and secret material. The important question is whether the bytes being verified match the bytes the provider signed.

Also check deployment timing. If the secret was updated in a dashboard after a serverless deploy, the runtime may still have the old value until redeploy. If several workers receive webhooks, one instance can accept while another rejects. Mark which environment handled the failing attempt.

Only rotate secrets after the verification path is understood or when compromise is suspected. In ordinary debugging, first separate provider delivery, transport, raw body verification, and business handler logic. That keeps the fix testable.

Webhook signature failure checklist before rotating secrets

// COMMENTS

ON THIS PAGE