webhook signature verification secret rotation

For webhook signature verification, secret rotation is usually done with an overlap period so you can accept both the old and new secrets while senders gradually switch over.

Recommended rotation pattern

1. Generate a new secret

   • Keep the current secret active.
   • Start using the new secret for newly signed webhooks.

2. Verify against both secrets

   • During the transition window, your verifier should try:
     • the new secret
     • the old secret
   • Accept the request if either matches.

3. Record which secret matched

   • Useful for monitoring rollout progress.
   • Helps you know when it’s safe to retire the old secret.

4. Retire the old secret

   • After all webhook senders are confirmed updated and any replay windows have passed, remove the old secret.

Security considerations

• Keep the overlap short to reduce the attack surface.
• Store secrets securely:
  • env vars, secret managers, vaults
• Use timestamps/nonces in signatures if supported, to reduce replay risk.
• Reject old timestamps beyond your allowed tolerance.
• Rotate on a schedule and also immediately if compromise is suspected.

Example verification logic

Pseudo-flow:

for secret in [current_secret, previous_secret]:
    if verify_signature(payload, signature, secret):
        accept
reject

Operational tips

• If you control both sides:
  • deploy verifier changes first to accept both secrets
  • then switch signers to the new secret
  • then remove the old secret after the cutoff
• If a provider controls signing:
  • ask whether they support multiple active secrets or a grace period

If you want, I can also give you:

• a language-specific example (Node/Python/Go/etc.)
• a rotation checklist
• or a secure verification implementation pattern.