Rotating a shared secret is normally a coordination problem: the moment you change it, anything still holding the old one starts failing. Webhook signing avoids that by signing with both secrets at once for a window, so there is no instant where only one of them works.
What actually happens when I rotate?
You call the rotate endpoint, and it returns a new secret once. Store it then; there is no way to retrieve it later.
From that moment, for the next 24 hours, Bird signs every delivery with both the old secret and the new one. The webhook-signature header carries both, space-delimited, in the form v1,<old> v1,<new>. After 24 hours the old secret stops signing.
So the overlap is the whole mechanism. An endpoint that still has only the old secret verifies against the old signature; one you have already deployed with the new secret verifies against the new one. Both are correct at the same time, which is what makes the deploy unhurried.
What does my handler have to do?
One thing, and it is the thing a hand-rolled verifier usually gets wrong: accept the delivery if any signature in the header matches, rather than reading the first one and comparing it.
The header can carry several signatures, and during a rotation it does. A handler that splits on whitespace and takes element zero will verify fine for months and then reject half its traffic the first time someone rotates. If you use a Standard Webhooks library, this is already handled: they try all signatures. If you wrote your own, this is the case to test.
The verification is otherwise unchanged, and how to verify a webhook signature covers the rest of it.
What is the safe sequence?
Four steps, and the only ordering that matters is that the deploy happens inside the window.
- Rotate, and capture the new secret from the response.
- Deploy it to your endpoint, alongside or in place of the old one.
- Confirm deliveries are verifying, from your own logs or the endpoint's delivery attempts.
- Do nothing else. The old secret expires on its own at the 24-hour mark.
There is no step that removes the old secret, and you should not need one. If you want the old secret dead sooner than that, the honest answer is that the overlap is the feature and shortening it reintroduces the problem rotation exists to avoid.
What if I rotate again straight away?
It fails, deliberately. An endpoint holds at most five concurrently valid secrets, so rotating repeatedly inside an overlap window is refused with a too-many-secrets error until an older one expires.
That ceiling is worth knowing because the situation it catches is a scripted rotation on a short schedule, which is the shape someone reaches for after a suspected leak. If a secret has leaked, rotate once and deploy; a second rotation minutes later does not make the first one more effective, and the fifth is refused.
What happens to deliveries that failed during the change?
Nothing you lose, if you fix the secret inside the retry window.
A delivery your endpoint rejected is retried on the normal schedule rather than discarded, which is roughly a day of attempts, and anything that fails past that can be replayed. So a rotation that briefly broke verification is recoverable, and how failed webhooks are retried has the schedule and the replay window.
The one thing to avoid during a rotation is returning 2xx for a delivery you could not verify. That tells us it was handled, and it is the one response that loses the event for good.