If you've seen webhook-id, webhook-timestamp and webhook-signature headers, you've already met Standard Webhooks. We go through the spec field by field and explain why each part is designed the way it is.
Standard Webhooks is a spec for how webhooks are signed and which headers carry the signature. The sender adds webhook-id, webhook-timestamp and webhook-signature, and signs id.timestamp.body with HMAC-SHA256. The receiver can verify with the same library no matter who sent the webhook. This post goes through the spec field by field and explains why each part is designed the way it is, based on the spec and the official site as of 2026-09-27.
The three headers
| Header | Contents | Example |
|---|---|---|
webhook-id |
A unique ID for the webhook | msg_2KWPBgLlAfxdpx2AI54pPJ85f4W |
webhook-timestamp |
When it was sent, as integer Unix seconds | 1674087231 |
webhook-signature |
The signature(s), space-delimited | v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= |
The signed content
The sender signs the ID, the timestamp and the body joined with dots:
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1674087231.{"type":"user.created","timestamp":"2023-01-19T00:13:51Z","data":{...}}
The spec stresses that the payload you sign must be exactly the payload you send. Serialize once, then use that same string for both. Receivers compute over the body exactly as received.
Why the ID is signed
Receivers deduplicate on webhook-id; the spec recommends using it as the idempotency key. Signing it means nobody can alter the ID in transit to make a replayed webhook look new. Senders keep the same ID across retries.
Why the timestamp is signed
To stop replay attacks, where someone captures a valid request and sends it again later. Receivers reject timestamps outside a tolerance window, and because the timestamp is signed, changing it breaks the signature. The official JavaScript, Python, Ruby, Go and PHP libraries all use a five-minute window in either direction.
Secrets and signature formats
HMAC (v1)
| Item | Value |
|---|---|
| Scheme | HMAC-SHA256 |
| Secret format |
whsec_ followed by base64 |
| Secret length | 24 bytes (192 bits) to 64 bytes (512 bits) recommended |
| Signature format |
v1, followed by base64 |
To use the secret, strip whsec_ and base64-decode the rest; those bytes are the HMAC key. Using the whsec_… string itself as the key gives a different signature.
import { createHmac } from 'node:crypto';
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const sig = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64');
const header = `v1,${sig}`;
Receivers must compare signatures in constant time, and the spec says so explicitly.
Asymmetric (v1a)
The spec also defines ed25519 signatures. Secret keys are base64 prefixed with whsk_, public keys with whpk_, and signatures are marked v1a. Receivers hold only the public key, so a leak on their side can't be used to forge webhooks.
Why multiple signatures
webhook-signature can hold several space-separated signatures, and a receiver accepts the message if any one matches:
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo=
During a rotation the sender signs with both the old and the new secret for a while. A receiver still on the old secret keeps verifying; once it switches to the new one, that signature matches too. Nobody has to change at the same instant. Rotating signing secrets covers the receiver side.
The v1 / v1a prefix exists so new schemes can be added later. Receivers skip signatures with versions they don't know.
Payload shape
The spec recommends a JSON body with three fields:
| Field | Contents |
|---|---|
type |
A hierarchical, full-stop delimited event type such as user.created, using [a-zA-Z0-9_]
|
timestamp |
When the event happened, ISO 8601 |
data |
The event data |
It recommends keeping payloads small, usually under 20 KB, and discusses both full payloads and thin payloads that carry only identifiers for the receiver to fetch.
Retry and response guidance
The spec also recommends sender behavior:
- Retries: exponential backoff over several days, for example immediately, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 14 h, 20 h, 24 h, with random jitter added.
- 2xx: success.
- 3xx: failure; update the webhook URL rather than following redirects.
- 410 Gone: the sender should disable the endpoint.
- 429, 502, 504: throttle.
- SSRF: proxy webhook requests and isolate workers in private subnets.
- HTTPS: recommended depending on how sensitive the payload is.
Who uses it
The official site's list of adopters (as of 2026-09-27) includes OpenAI, Anthropic, Google Gemini, Twilio, Kong, Svix, Brex, PagerDuty, Etsy, Resend, Clerk.dev, ngrok, Render and Lob, among others. The technical steering committee has members from Zapier, Twilio, Lob, Mux, ngrok, Supabase, Svix and Kong.
svix-* headers
Webhooks from Resend or Clerk arrive with svix-id, svix-timestamp and svix-signature. They are delivered through Svix and use the same signature scheme under different header names (Svix manual verification); verifying svix-* webhooks covers the header mapping and the Resend and Clerk SDKs.
Libraries
The spec's repository has libraries for C#, Elixir, Go, Java, JavaScript, PHP, Python, Ruby and Rust.
| Language | Install | Verify |
|---|---|---|
| JavaScript / TypeScript | npm install standardwebhooks |
new Webhook(secret).verify(body, headers) |
| Python | pip install standardwebhooks |
Webhook(secret).verify(body, headers) |
| Ruby | gem install standardwebhooks |
StandardWebhooks::Webhook.new(secret).verify(body, headers) |
| Go | github.com/standard-webhooks/standard-webhooks/libraries/go |
standardwebhooks.NewWebhook(secret), then wh.Verify(body, r.Header)
|
Every library expects the body exactly as received; getting the raw request body shows how to get it in eight frameworks.
Migrating from a custom format
The spec recommends adding the Standard Webhooks headers without removing your existing ones. Receivers switch to the new headers when they're ready, and you drop the old ones once they have. Switching delivery providers is covered in migrating webhook providers.
How Webhook Admin signs
Webhook Admin signs in the Standard Webhooks format (as of 2026-09-27):
- Headers:
webhook-id(msg_…),webhook-timestamp(seconds),webhook-signature(v1,…). - Secrets: generated per endpoint,
whsec_plus 24 random bytes in base64. - Body:
{ "type", "timestamp", "data" }. - Retries and manual replays keep the same
webhook-id; the timestamp and signature are regenerated on every attempt. - For 24 hours after a rotation, messages carry signatures from both the old and the new secret.
A few things differ from the spec's recommendations. By default, retries run immediately, then after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h (8 attempts over about 28 hours; you can choose the number of retries and the interval per endpoint), sent at the scheduled times. To avoid bursts, each endpoint gets at most 10 concurrent deliveries, and after 5 consecutive failures sending to it pauses for 30 seconds. A 410 is retried like any other failure rather than disabling the endpoint; an endpoint that keeps failing for five days is disabled automatically. Asymmetric v1a signatures aren't supported.
Receivers can verify with any official library above or with Webhook.verify from the webhookadmin npm package. The signing string is documented under signature scheme and libraries under libraries. If a signature won't verify, see why webhook signature verification fails.
If you want to send Standard Webhooks-signed webhooks with retries and delivery logs, you can try Webhook Admin for free (50,000 messages a month): https://app.webhookadmin.com/signup
Quick FAQ
Should we move our own signature format to Standard Webhooks?
For a new implementation, yes - receivers get official libraries in most languages. For an existing one, the spec recommends adding the Standard Webhooks headers alongside your current ones instead of replacing them, so receivers can switch when they're ready.
What is the v1a asymmetric signature?
An ed25519 signature defined by the spec, with secret keys prefixed whsk_ and public keys prefixed whpk_. Receivers only hold the public key, so a leak on their side doesn't let anyone forge webhooks. It goes in the same header, marked v1a instead of v1.
How do svix-* headers relate to Standard Webhooks?
Same signature scheme, different header prefix. Svix webhooks use svix-id, svix-timestamp and svix-signature, sign id.timestamp.body, and use whsec_ base64 secrets. Svix's libraries also accept webhook- prefixed headers.
Thanks for reading! Are you sending or receiving Standard Webhooks yet, or using a scheme of your own? Let us know in the comments.
This post first appeared on the Webhook Admin blog.
Top comments (0)