Rotate webhook secrets as Stripe

RaccoonDev — Sun, 08 Nov 2026 05:46:39 +0000

When adding a new feature that requires a webhook, you usually think about delivering it, signing it, maybe deduplicating it, and retry logic. But today I want to share one of the best practices for rotating webhook secrets.

The main logic of Stripe's secret rerolling

You can choose your secret expiration either immediately or up to 24 hours later.
If you choose the second option, your OLD secret will stay valid for that period, and all webhook messages will be signed with both secrets.
Maybe you will have lots of questions: is it safe? How can we sign the same message with two secrets? And the reasonable one: what is the purpose of it? Now I will answer all of them.

What if the webhook secret is compromised? Will a hacker have access for 24 hours?

Of course not. It is easy to confuse a webhook secret with an API key. So I will remind you of the difference:

A webhook secret is used by the customer's service to check the author of the message. It is validated on the client side.
An API key is used by our server to check user permissions, credits, etc. It is validated on our side.

If a hacker obtains a user's webhook secret, the user rerolls it in our service as soon as they notice it and changes it in project settings. The old one is still valid on our side, but the user has already replaced it in project settings, so a forged message signed with the old secret fails verification on their side.

Keep in mind that until the user updates their settings, the old secret is still accepted there. So after a confirmed leak, choose immediate expiration. The 24-hour window is for planned rotation, not for incident response.

How can we deliver a webhook with multiple signatures?

We generate one signature per active secret and put all of them into a single header. The timestamp is part of the signed string, which protects from replay attacks:

X-Webhook-Signature: t=1731038940,v1=<hmac_with_new_secret>,v1=<hmac_with_old_secret>

Sender side: sign with every active secret.

import hmac, hashlib, time

def sign(secret, ts, body):
    return hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()

def header(secrets, body):
    ts = int(time.time())
    return f"t={ts}," + ",".join(f"v1={sign(s, ts, body)}" for s in secrets)

header(["whsec_old"], body)
header(["whsec_new", "whsec_old"], body)

Receiver side: it is enough that any signature matches any secret the client knows.

So a client that is still on the old secret and a client that has already switched to the new one both pass verification with the same message. After 24 hours we simply stop signing with the old secret.

What is the purpose of it?

Imagine you are a DevOps engineer who wants to reroll a secret due to basic safety checks, and you create a new secret in the UI, copy it, go to project settings, paste it, and rerun the project. Overall it will take 10-15 minutes, and during this time some messages will fail verification because of mismatched secrets. They will get a 401 and go to the retry queue, but if the retries run out before the new secret is in place, those messages are lost.

This chance is small, but when you are building software for 20+ companies, you should remember that this may happen sooner or later. With two signatures, the client can switch secrets at any moment inside the window, and nothing is lost.

Overall, it is just one of the best practices, and it is not always good for you and your projects, so always think before developing.

DEV Community: RaccoonDev

Rotate webhook secrets as Stripe

The main logic of Stripe's secret rerolling

What if the webhook secret is compromised? Will a hacker have access for 24 hours?

How can we deliver a webhook with multiple signatures?

What is the purpose of it?