Rotate Webhook Signing Secrets
Rotate webhook signing keys without losing valid deliveries or accepting retired signatures after the overlap window ends.
A webhook signer and receiver must agree on a secret while events continue to arrive. An abrupt change can drop valid deliveries. An overlap that never ends leaves the old credential useful after rotation. OWASP's webhook guidance covers authentication, replay protection, and secure secret handling; the exact provider protocol still controls this cutover.
Identify whether the provider signs with one key, multiple active keys, or a key ID in the header. Record the algorithm, raw-body input, timestamp rule, and retry behavior. Do not change signature verification code and provider keys in one unreviewed step.
Acceptance window
| Phase | New signature | Old signature | Operator action |
|---|---|---|---|
| Before cutover | Not yet active | Accept | Deploy dual-verifier if supported |
| Overlap | Accept | Accept only within stated window | Monitor real delivery IDs |
| Retirement | Accept | Reject | Revoke old provider key |
| After retirement | Accept | Reject replay and stale timestamp | Save test receipt |
If dual verification is unavailable, plan a short maintenance or retry-backed transition according to the provider's behavior. Do not make an unlimited fallback path. Bind each accepted event to its tenant and endpoint. Verify the signature over the exact raw body; parsing and re-serializing JSON before verification can change bytes.
Test both sides
Use provider test events or an owned mock. Confirm a valid old-key event before cutover, a valid new-key event after activation, and rejection of a forged signature. During overlap, test duplicate delivery and timestamp replay. After retirement, require old-key rejection while new-key deliveries still process once.
Keep only safe key IDs and event IDs in the cutover log. Do not record signing secrets or full private payloads. Check queued retries after the overlap ends; decide whether they should be rejected, re-signed, or handled through a provider-specific recovery path. A configuration update is not completion evidence. Close the rotation only after both delivery health and old-key rejection are demonstrated.
Make offboarding verifiable
Use the offboarding checklist to identify owners, revoke grants and verify the result. Discuss a scoped review of your application's access controls.