How do I rotate a webhook secret without downtime?

Your receivers may deploy at different times. An overlap lets a receiver using the old secret and a receiver using the new secret authenticate the same delivery.

Keep verifying deliveries throughout the deployment so a request from an attacker cannot trigger work.

What happens when I rotate?

Bird gives you a new signing secret. Deploy it within 24 hours, while Bird still signs with the old secret.

Call rotateWebhookSecret for your endpoint. Save its secret, a non-empty string beginning with whsec_, because it is returned only in that response.

Bird signs each delivery with both secrets during the overlap. The webhook-signature header contains space-separated signatures, each beginning with v1,.

A receiver can verify either signature using the corresponding secret. Complete the deployment within 24 hours because the old secret stops signing after that window.

What does my handler have to do?

Your handler must accept a delivery when any supplied signature matches a secret it trusts.

A receiver that checks only the first signature can reject valid deliveries after it switches secrets.

The Standard Webhooks specification defines a list of signatures so receivers can try each during rotation. Test your verifier with multiple signatures before rotating a live endpoint.

Keep the timestamp and duplicate checks in place throughout the change. Signature verification covers those checks.

What is the safe sequence?

Save and deploy the new secret. Confirm verification before the old secret's overlap ends.

1. Rotate the endpoint secret and store the returned value immediately.
2. Deploy the new value to every receiver instance within the 24-hour overlap.
3. Confirm that receivers verify deliveries using the new secret, through receiver logs and Bird's delivery attempts.
4. Let the previous secret expire automatically after the overlap.

There is no separate removal step in the rotation operation. If the old secret was exposed, stop trusting it in your receivers after they have the new one. Rotating alone leaves receivers that trust the old secret exposed during the overlap.

What if I rotate again straight away?

Another rotation can succeed until the endpoint reaches five concurrently valid secrets.

Starting with one secret, four rotations can fill those five slots before older secrets expire. The next rotation fails with WebhookTooManySecrets. A rotation loop can therefore prevent another secret from being issued when you need it.

Wait for an older secret to expire before rotating again. Repeated rotation does not remove the need to deploy the new secret to your receivers.

What happens to deliveries that failed during the change?

Bird retries failed deliveries, so repairing verification can recover them during the retry window.

The schedule spans roughly 27.5 hours before timing adjustments. A failed delivery can also be recovered through replay after retries finish; failed webhook retries explains the replay window.

Return an error for a request you cannot verify. Returning 2xx marks the delivery successful, which excludes it from missed-event replay.