What is a webhook secret?

A webhook secret, also called a signing secret, is the shared key a provider uses to sign each webhook and the receiver uses to verify the signature. The provider computes an HMAC-SHA256 over the message using the secret and sends the result in a header; the receiver recomputes it with its copy and compares. Anyone can POST to a public endpoint, but only a holder of the secret can produce a signature that verifies.

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.

The whsec_ format

Under the Standard Webhooks specification, the symmetric signing secret is a base64-encoded key of 24 to 64 random bytes, carried with a whsec_ prefix:

whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw

The prefix is there for humans and tools rather than cryptography. It makes the string recognizable in a config file, lets secret scanners flag one committed to a repository, and prevents a class of mistakes where some other token is pasted where a signing secret belongs. Providers that follow the spec, Svix among them, hand you a whsec_ value when you create an endpoint; verification libraries strip the prefix and base64-decode the rest before computing the HMAC.

The spec also defines an asymmetric variant, where the provider signs with a private key (whsk_ prefix) and receivers verify with the public key (whpk_). Symmetric whsec_ secrets remain the common default.

One secret per endpoint

Well-designed providers generate a distinct secret for each endpoint rather than one per account. The blast radius of a leak stays contained to a single endpoint, and rotating one integration's secret doesn't break the others. This is also the spec's recommendation. When you register the same receiving URL with several providers, you hold several secrets, and your handler picks the right one by route or by which provider it is verifying.

Handling the secret on the receiving side

A webhook secret is a credential and deserves the same handling as an API key.

• Keep it out of code. Load it from an environment variable or a secrets manager, never a committed config file. The whsec_ prefix makes leaked secrets easy for scanners to catch, but the better outcome is having nothing to catch.
• Fetch it, don't retype it. Copy the secret from the provider's dashboard or API at setup time. A secret that has been through a chat message or a ticket has been exposed.
• Treat verification failure as a signal. A sudden run of signature failures usually means the secret was rotated on one side and not the other, which is a configuration incident rather than an attack, but the response, checking both sides hold the same value, is the same.

Rotation

Secrets need a rotation story, both for routine hygiene and for the day one leaks. The mechanics are built into the signature scheme: during a rotation window the provider signs each message with both the old and the new secret, sending multiple space-delimited signatures in the header. A receiver holding either secret verifies successfully, so the two sides don't have to switch in the same instant. Once the window passes, the old secret stops signing and can be discarded.

If a secret is exposed, rotate it immediately rather than waiting for a schedule. The exposure window plus the timestamp tolerance is how long captured traffic can be forged or replayed.

For the broader picture of what the secret protects against, see webhook security and the security best practices.

Frequently asked questions

Where do I find my webhook secret?

In the provider's dashboard or API, attached to the endpoint you registered. Providers following the Standard Webhooks specification show it as a whsec_-prefixed string. It is generated by the provider; you don't choose it yourself.

What does the whsec_ prefix mean?

It marks the string as a Standard Webhooks symmetric signing secret. The prefix is not part of the key material: verification libraries strip it and base64-decode the remainder. Its value is recognizability, in config files and to secret scanners.

Is a webhook secret the same as an API key?

No. An API key authenticates requests you make to the provider. A webhook secret verifies requests the provider makes to you, and it can only produce signatures, not API calls. That asymmetry is deliberate: a leaked signing secret exposes less than a leaked API key.

How do I rotate a webhook secret without downtime?

Use the provider's rotation flow. During the rotation window messages are signed with both the old and new secret and carry multiple signatures, so verification succeeds whichever one you hold. Update your stored secret within the window and nothing fails.