What is a signing secret rotation?
Signing secret rotation is the operational process of replacing a webhook's shared secret with a new one without dropping in-flight deliveries. The two-secret window is the standard pattern: generate the new secret, configure the receiver to accept either old or new, switch the source to sign with the new secret, wait until in-flight retries from before the switch have drained (5-30 minutes), then remove the old secret. Stripe, GitHub, and Shopify each support this dual-secret window in their dashboards. Rotate routinely (quarterly), immediately on suspected leak, and on personnel changes touching the secret.
Rotation is replacing a shared secret without breaking verification on legitimate inbound webhooks during the transition. It's straightforward in theory and surprisingly fragile in practice.
The two-secret window is the standard pattern. At time T0, generate the new secret on the source. Configure the source to sign with both old and new (or to switch). Configure the receiver to *accept either* old or new. At time T1 (5-30 minutes later, depending on retry windows), confirm that all in-flight retries from before T0 have either succeeded or expired. Remove the old secret from the receiver. From this point only the new secret verifies; any leaked copy of the old secret is useless.
Most providers' dashboards support this. Stripe lets you create a new endpoint signing secret while leaving the old one active; once you've migrated, you delete the old. GitHub allows two secrets per webhook. Shopify rotates by issuing a new app-level secret and propagating to all webhooks. Read your provider's specific rotation flow before relying on the generic pattern.
When to rotate, in order of urgency:
- Immediately: suspected secret leak (logged accidentally, committed to git, employee with access offboarded under bad circumstances). Don't wait — rotate, then investigate. - Quarterly: routine hygiene. Most teams skip this; doing it builds the muscle memory for emergency rotation. - On personnel change: anyone with access to the secret leaving the org should trigger rotation, even if access was nominally revoked. - On framework upgrade: when changing webhook libraries or middleware, rotate to ensure old code paths can't accidentally re-emerge.
Rotation pitfalls:
- No two-secret window. "Generate new, paste new, restart" produces a 5-minute outage of webhook verification. Avoid in production. - Forgetting one environment. Production secret rotated, staging still on the old. Half your test webhooks fail. - Source-side caching. Some providers cache signing secrets at edge; the new secret takes minutes to propagate. Test with a known event before declaring rotation complete. - Secret in code. If the secret is committed (it shouldn't be, but happens), rotation also requires force-pushing to remove from history — and even then, every fork and clone retains it.
Document the rotation runbook. The first rotation is always the rough one because the runbook is being written; subsequent rotations are operational.
See Signing Secret Rotation in real traffic
WebhookWhisper captures every webhook with full headers, body, signature, and timing — so concepts like signing secret rotation stop being abstract and become something you can inspect.
Start Free