Checking signatures
Verify that a webhook came from us, unchanged and recent, with any Standard Webhooks library or a few lines of code.
Every webhook is signed the Standard Webhooks way, with your endpoint's secret. Check the signature before you trust a delivery: anyone can send a POST to your address.
The headers
content-type: application/json
user-agent: daxov-webhooks/1
webhook-id: evt_3Kp8Zr1WqN6xBv4MhS9a
webhook-timestamp: 1793300100
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=webhook-id: the event's id. It is the same on every retry and replay: dedupe on it.webhook-timestamp: unix seconds when this attempt was sent. It is signed, so an old delivery can't be replayed later.webhook-signature: onev1,<base64>for each secret still signing, separated by spaces. There are two for a while after you rotate the secret.
How to check it
The signature is the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{the raw body}, keyed with the bytes of your secret: the base64 after whsec_.
- Read the raw body, exactly as it arrived, before any JSON parsing.
- Refuse a timestamp more than 5 minutes away from now.
- Compute the signature and compare it in constant time.
- Accept if any
v1,signature in the header matches.
With a library
Any Standard Webhooks library does all four steps. They exist for Node, Python, Go, Rust, PHP, Ruby and more.
// npm i standardwebhooks
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.WEBHOOK_SECRET); // whsec_…
// rawBody: the request's body as it arrived; headers: its headers as an object.
const event = wh.verify(rawBody, headers); // throws when the signature doesn't check outBy hand
import crypto from "node:crypto";
// rawBody: the request's body exactly as it arrived, as a string.
export function verifyWebhook(secret, headers, rawBody) {
const id = headers["webhook-id"], timestamp = headers["webhook-timestamp"], signatures = headers["webhook-signature"] ?? "";
if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
return signatures.split(" ").some((s) => {
if (!s.startsWith("v1,")) return false;
const given = Buffer.from(s.slice(3), "base64");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
}Check the raw body
Parsing the JSON and writing it out again changes its bytes, and the signature won't match. In Express, read it with express.raw({ type: "application/json" }); in Flask, with request.get_data(). Parse the JSON only after the check.
Our server SDK has the same check, verifyWebhook, and readWebhook, which checks and parses in one go: see the client SDK.
Rotating the secret
/v1/webhooks/{webhook_id}/rotateMakes a new secret and answers it once, with the endpoint: { "webhook": {…}, "secret": "whsec_…" }. The old secret also signs for grace_seconds: 86,400 (a day) unless you send another number, from 0 to 604,800 (7 days). While both sign, webhook-signature carries two signatures, so you can switch your servers over without missing a delivery. The endpoint's previous_secret_until_unix says until when the old one signs.
{ "grace_seconds": 3600 }If a secret has leaked, rotate with "grace_seconds": 0: the old one stops at once.
Tools are signed the same way
When a character calls one of your tools, the request to your tool's address is signed exactly like a webhook, with the tool's own secret. The same check works; webhook-id is then the tool call's id (tcl_…).