A webhook receiver checks the signature to confirm a request really came from the sender. Every provider signs differently, though, so each new integration means looking up a new header name, a new string to sign and a new way to handle the key. Standard Webhooks is an open specification that gives webhook signatures and headers one common format. This article walks through what the spec defines and how to verify signatures on the receiving side.
Based on version 1.0.0 of the spec and public documentation as of September 2026. See the references at the end.
Overview
Standard Webhooks was led by Svix, a webhook sending service, and announced in December 2023. The spec and libraries are on GitHub, and the spec is licensed under Apache License 2.0.
A technical steering committee guides the project. As of September 2026 its members are engineers from Zapier, Twilio, Lob, Mux, ngrok, Supabase, Svix and Kong.
The problem it addresses is fragmentation. Receivers relearn verification for every new provider, and senders keep re-solving the same design questions. Standard Webhooks puts the signature scheme, headers, payload shape and retry guidance into one spec.
The three headers
A webhook that follows Standard Webhooks sends three headers with the body.
| Header | Meaning | Example |
|---|---|---|
webhook-id | Unique ID for the event; stays the same across retries | msg_2KWPBgLlAfxdpx2AI54pPJ85f4W |
webhook-timestamp | Time of this delivery attempt (Unix seconds) | 1674087231 |
webhook-signature | Signature(s), space-delimited when there is more than one | v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= |
webhook-id belongs to the event, so retries carry the same value. webhook-timestamp belongs to the attempt, so it changes on every retry.
How the signature is computed
There are two schemes: symmetric (v1) and asymmetric (v1a).
Symmetric (v1)
Sender and receiver share one key, and the signature is HMAC-SHA256.
- Join
webhook-id,webhook-timestampand the body with periods (msg_xxx.1674087231.{"type":"order.paid",...}) - Compute HMAC-SHA256 with the key and base64-encode the result
- Prefix it with
v1,and put it inwebhook-signature
The key is 24 to 64 random bytes, base64-encoded and prefixed with whsec_ when handed to the receiver. The HMAC uses the bytes you get by stripping whsec_ and decoding the base64.
Asymmetric (v1a)
This scheme uses an Ed25519 key pair. The sender signs with the secret key (prefixed whsk_) and the receiver verifies with the public key (prefixed whpk_). Because the receiver never holds a secret, the spec recommends asymmetric signatures, at the cost of more CPU than HMAC.
What the receiver checks
Beyond matching the signature, the spec asks receivers to:
- Check the timestamp. Reject
webhook-timestampvalues outside a tolerance window to stop replay attacks. The official JavaScript library allows five minutes either way - Deduplicate on
webhook-id. Use it as an idempotency key, because retries and network issues can deliver the same event more than once - Compare in constant time. Compare symmetric signatures with a constant-time function; ordinary string comparison opens the door to timing attacks
- Verify the raw body. Parsing the body as JSON and serializing it again changes whitespace or key order and breaks the signature
Key rotation
webhook-signature can hold several signatures so keys can be rotated without downtime. After a rotation the sender signs with both the new and the old key for a set period and sends both, separated by a space. The receiver accepts the request if either one matches, so updating to the new key at any point during that window keeps deliveries flowing.
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4= v1,PGOol9edfeMgYBaSh+rI9ThEyc0IoEXMU2Xteb3Pl68=
Official libraries
Official libraries for signing and verifying are published for nine languages.
- Python (
standardwebhookson PyPI) - JavaScript/TypeScript (
standardwebhookson npm) - Java/Kotlin (Maven Central)
- Rust (
standardwebhookson crates.io) - Go, Ruby, PHP, C# and Elixir
Community implementations exist for Haskell, Swift and others.
Verifying in Node.js
With the official library
An Express receiver. express.raw() keeps the body as raw bytes, which go straight to verify. It throws if the signature does not match or the timestamp is out of range.
import express from 'express';
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.WEBHOOK_SECRET); // starts with whsec_
const app = express();
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = wh.verify(req.body.toString('utf8'), req.headers);
} catch {
return res.status(400).end();
}
// check webhook-id against already-processed events first
console.log(req.headers['webhook-id'], event.type);
res.status(204).end();
});
app.listen(3000);
Without a library
The same check with only Node’s built-in crypto, including the timestamp window, multiple signatures and constant-time comparison.
import crypto from 'node:crypto';
function verify(secret, headers, body, toleranceSec = 300) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const sigHeader = headers['webhook-signature'];
if (!id || !ts || !sigHeader) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > toleranceSec) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest();
return sigHeader.split(' ').some((s) => {
const [ver, sig] = s.split(',');
if (ver !== 'v1' || !sig) return false;
const got = Buffer.from(sig, 'base64');
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
});
}
Pass the body exactly as received.
Who uses it
The Standard Webhooks site lists OpenAI, Anthropic, Google Gemini, Twilio, Kong, PagerDuty, Supabase and others as compatible. In their own developer docs:
- OpenAI states that its webhooks follow the Standard Webhooks spec and can be verified with the Standard Webhooks libraries
- Supabase implements the spec for Auth HTTP hooks and uses
standardwebhooksin its verification example - Anthropic sends
webhook-id,webhook-timestampandwebhook-signaturewith awhsec_secret for Claude Managed Agents webhooks, and the SDK rejects deliveries older than five minutes
If you receive webhooks from several of these, one verification routine covers them all.
On the sending side
Our webhook platform, Webhook Admin, signs every webhook in the Standard Webhooks format (v1). Each endpoint gets its own whsec_ secret, and for 24 hours after a rotation deliveries are signed with both the old and the new key. Receivers can verify with the code above or any official library. Retries, delivery logs and failure alerts come with it, so you can send Standard Webhooks without building the sending side yourself.
References
- Standard Webhooks
- Standard Webhooks: Specification (GitHub)
- Standard Webhooks: Repository README (libraries and steering committee)
- Standard Webhooks: JavaScript library
- Svix Blog: Announcing Standard Webhooks
- OpenAI: Webhooks
- Supabase: Auth Hooks
- Claude Platform Docs: Subscribe to webhooks
FAQ
Which languages can verify Standard Webhooks signatures?
Official libraries exist for nine languages: Python, JavaScript/TypeScript, Java/Kotlin, Rust, Go, Ruby, PHP, C# and Elixir. In Node.js, install standardwebhooks from npm and pass the received body and headers to the verify method of the Webhook class.
What is the most common reason signature verification fails?
Parsing the body as JSON and serializing it again before verifying. A single changed space or key order breaks the signature. Always verify against the raw bytes you received.
Can we move from our own signature format to Standard Webhooks?
The spec describes a migration path: keep your existing headers and add the Standard Webhooks headers alongside them. The existing signing secret can be reused, so receivers can switch to the new format whenever they are ready.