What is secret rotation?

Secret rotation is replacing a webhook secret with a new one while keeping signature verification working throughout the change. Because the provider signs with the secret and the receiver verifies with its own copy, a naive swap breaks every delivery between the moment one side changes and the moment the other catches up. Rotation schemes exist to make that window harmless.

Sending webhooks?

Svix is the enterprise-ready webhook sending service. It handles signing, retries, and delivery observability, so you can ship a reliable webhook platform in minutes instead of months. Start sending webhooks with Svix.

Why secrets get rotated

There are two triggers. The first is exposure: the secret appeared in a commit, a log line, a support ticket, or a departing contractor's laptop, and every minute it remains valid is a minute an attacker can forge deliveries that pass signature verification. The second is hygiene: rotating on a schedule bounds the value of any leak you didn't detect, the same reasoning behind rotating API keys and TLS certificates.

The two triggers deserve different urgency. A scheduled rotation can take a leisurely path through the overlap window described below. A known exposure calls for immediate rotation, and some providers offer an expedited path that invalidates the old secret at once, trading a brief verification gap for a closed attack window.

How zero-downtime rotation works

The mechanics are built into the signature scheme rather than bolted on. Under the Standard Webhooks specification, the webhook-signature header holds a space-delimited list of signatures, not just one. During a rotation window the provider signs each message with both the old and the new secret and sends both signatures. A receiver holding either secret finds a signature that matches, so verification succeeds no matter which side of the swap the receiver is on.

The sequence looks like this:

1. The provider generates a new secret and begins dual-signing. The receiver has done nothing yet, and old-secret verification still works.
2. The receiver fetches the new secret and swaps it in, at any convenient moment inside the window. New-secret verification works because the new signature is already in every delivery.
3. The window closes, commonly after 24 hours. The provider stops signing with the old secret and discards it.

At no point do the two sides need to move simultaneously, which is what makes the rotation zero-downtime. Svix exposes exactly this flow: rotating an endpoint's secret keeps the old key signing alongside the new one for 24 hours.

Receiver-side practice

The receiving side of a rotation is mostly discipline rather than code, since verification libraries already check every signature in the header.

• Store the secret somewhere swappable. A secrets manager or environment variable can be updated without a deploy; a hardcoded string cannot, and turns a 24-hour window into a race against your release process.
• Watch for verification failures after the window. A receiver that missed the window fails closed, which is correct but silent. A burst of signature failures on one endpoint right after a rotation window ends almost always means the new secret never got installed.
• Rotate deliberately, not reflexively. Rotation touches two parties. Coordinating it through the provider's supported flow beats ad hoc secret swaps that assume both sides move at once.

For where the secret fits in the wider picture, see webhook security and the security best practices.

Frequently asked questions

How does webhook secret rotation avoid downtime?

During the rotation window the provider signs every message with both the old and new secret, sending multiple signatures in the webhook-signature header. A receiver holding either secret verifies successfully, so the two sides update independently instead of simultaneously.

How often should webhook secrets be rotated?

Immediately on any suspected exposure, and otherwise on the same cadence as your other credentials, commonly quarterly or yearly. Scheduled rotation bounds the damage of a leak you never detected, and with dual-signing windows it costs nothing operationally.

What happens if I miss the rotation window?

Once the provider stops signing with the old secret, a receiver still holding it rejects every delivery. Failed deliveries enter the provider's retry schedule, so installing the new secret promptly usually recovers the traffic; anything past retries can be replayed from delivery logs.

Do I need to rotate secrets for every endpoint at once?

No. Well-designed providers issue one secret per endpoint precisely so each can rotate independently. A leak affecting one endpoint is contained and fixed there without touching the others.