Blog · · 5 min read
Verifying Standard Webhooks Signatures
How to verify Standard Webhooks signatures: the three headers, the signed string, the whsec_ key, timestamp checks and rotation, with Node.js and Python code.
Key points
- A Standard Webhooks signature is base64(HMAC-SHA256(key, "webhook-id.webhook-timestamp.body")), sent as v1,
in the webhook-signature header. - The key is the base64 part after whsec_, decoded to bytes, and the body must be the exact raw bytes you received - not re-serialized JSON.
- Reject timestamps more than 5 minutes off, accept if any of the space-separated signatures matches, and use webhook-id to drop duplicates.
A Standard Webhooks signature is an HMAC-SHA256 over webhook-id, webhook-timestamp and the raw body joined with dots, base64-encoded. To verify it, recompute that value with your secret, compare it to the webhook-signature header, and check the timestamp is recent. The official libraries do it in a couple of lines; most bugs come from passing parsed JSON instead of the raw body, or using the whsec_ secret as-is. Here's how it works and how to get it right. The full spec lives in the Standard Webhooks repository.
The three headers
Every signed request carries three headers. If any is missing, reject the request.
| Header | Contains | Used for |
|---|---|---|
webhook-id |
A unique ID per message | Signature input, deduplication |
webhook-timestamp |
Send time, Unix seconds | Signature input, rejecting stale requests |
webhook-signature |
v1,<base64>, possibly several separated by spaces |
Comparing with your computed value |
The ID and timestamp are part of the signed content so nobody can tamper with them. An attacker can't relabel a message as a new one, or replay an old request with a fresh timestamp, without breaking the signature.
What gets signed, and with which key
The signed content is id.timestamp.body:
msg_2KWPBgLlAfxdpx2AI54pPJ85f4W.1733376000.{"type":"tool.call","tool":"find_slots",...}Secrets are handed out as strings starting with whsec_. Don't use that string directly as the HMAC key. Strip the whsec_ prefix and base64-decode the rest; those bytes are the key. Get this wrong and your code runs fine, but no signature ever matches.
Verification, step by step
This is what the official libraries do. If you write your own, follow the same order:
- Read the three headers. Reject with 400 if any is missing.
- Check that
webhook-timestampis within 5 minutes of now (the window the official libraries use). - Strip
whsec_from the secret and base64-decode it. - Compute HMAC-SHA256 over
id.timestamp.bodyusing the raw body bytes, then base64-encode. - Split
webhook-signatureon spaces. Accept if anyv1,entry matches step 4, compared in constant time. - Record the
webhook-id. If the same ID shows up again, return 2xx without processing it twice.
Node.js
With the standardwebhooks npm package. In Express, use express.raw so you get the body before anything parses it.
import express from 'express';
import { Webhook } from 'standardwebhooks';
const app = express();
const wh = new Webhook(process.env.VOICAST_TOOLS_SECRET!); // whsec_...
app.post('/voicast/tools', express.raw({ type: 'application/json' }), (req, res) => {
let body: any;
try {
body = wh.verify(req.body, req.headers as Record<string, string>);
} catch {
return res.status(401).json({ error: 'invalid signature' });
}
// body is the verified, parsed JSON
res.json({ ok: true, tool: body.tool });
});
app.listen(3000);Without the library, using only node:crypto:
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret: string, raw: Buffer, h: Record<string, string | undefined>): boolean {
const id = h['webhook-id'];
const ts = h['webhook-timestamp'];
const sigs = (h['webhook-signature'] ?? '').split(' ');
if (!id || !ts || !/^\d+$/.test(ts)) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${ts}.`).update(raw).digest();
return sigs.some((s) => {
const [ver, b64] = s.split(',');
if (ver !== 'v1' || !b64) return false;
const got = Buffer.from(b64, 'base64');
return got.length === expected.length && timingSafeEqual(got, expected);
});
}Python
The Python package (pip install standardwebhooks) accepts the whsec_ secret directly and lowercases header names before checking. Failures raise WebhookVerificationError.
import os
from flask import Flask, request, jsonify
from standardwebhooks.webhooks import Webhook, WebhookVerificationError
app = Flask(__name__)
wh = Webhook(os.environ["VOICAST_TOOLS_SECRET"]) # whsec_...
@app.post("/voicast/tools")
def tools():
try:
body = wh.verify(request.get_data(), dict(request.headers))
except WebhookVerificationError:
return jsonify(error="invalid signature"), 401
return jsonify(ok=True, tool=body["tool"])When signatures don't match
| Symptom | Likely cause | Fix |
|---|---|---|
| Never matches | Body was parsed as JSON and re-serialized | Pass the raw body (express.raw, request.get_data()) |
| Never matches | whsec_... string used directly as the key |
Strip the prefix and base64-decode (libraries do this for you) |
| Fails intermittently | Server clock drift | Sync the clock with NTP |
| Fails only right after a key rotation | Only the first signature is checked | Check every space-separated signature |
| Fails only in production | Using the test environment's secret | Confirm which environment the secret belongs to |
Body-parsing middleware is the usual suspect. Frameworks like Express, Next.js API routes and FastAPI all make it easy to read JSON and hard to keep the original bytes; whitespace or key order changes are enough to break the HMAC.
Rotating keys without downtime
During a rotation, the sender signs each message with both the old and new keys and puts both signatures in webhook-signature. Because your receiver accepts any matching signature, it keeps working whether it holds the old key or the new one. The only rule on your side: check all signatures, not just the first.
Doing this with voicast
voicast signs with Standard Webhooks in two places:
- In-call tools. When the AI decides to use a tool, voicast POSTs
{ type: 'tool.call', tool, arguments, call }to the tool'surl. There's one signing secret (whsec_...) per environment, which you can see in the dashboard or with the MCP toolget_tools_secret. After you rotate it, voicast also includes a signature with the old key for 24 hours. - Post-call webhooks. Events such as
call.endedandcall.summary_readyare sent by voicast with Standard Webhooks signatures. You register the endpoint on the portal page linked fromPOST /v1/webhooks/portal.
voicast waits up to 8 seconds for a tool to respond, so let the library handle verification and keep anything slow out of the request path. See function calling in live calls for tool design and post-call webhooks for the events.
FAQ
Can I widen the timestamp window beyond 5 minutes?
You can, but every extra minute is more time for a captured request to be replayed successfully. If clock drift is the real problem, fix the clock with NTP rather than loosening the check.
What should I do with webhook-id?
Use it for deduplication. Senders reuse the same ID when they retry, so store the IDs you've processed and return 2xx without doing the work again when a known ID arrives.
If the signature checks out, do I still need an IP allowlist?
A valid signature already proves the message came from someone holding the secret. An allowlist can be an extra layer, but sender IPs can change, so never use it instead of signature verification.