Anyone who finds your webhook URL can post to it. The signature is the only thing that separates an Anton delivery from a forgery, so a handler that updates a payout before it checks the signature has no security at all. Webhook signing defines the scheme; this page is the handler.
What you check
Every delivery carries X-Webhook-Timestamp (Unix seconds) and X-Webhook-Signature. Anton computes an HMAC-SHA256 over the string {timestamp}.{raw body} with your secret and sends it as lowercase hex, prefixed v1=.
Your handler does the same sum and compares. Do these steps in this order.
Take the bytes before any JSON parsing. Parse and re-serialise, and whitespace, key order and number formatting change, so a genuine delivery fails. In Express that means express.raw() on this route, not express.json().
Refuse a delivery whose timestamp is more than 300 seconds from your clock, in either direction. Without this window, one captured delivery can be replayed forever.
Hex-encode your HMAC and compare it to every v1= entry in the header with a constant-time function. Accept on any match. A plain == leaks how many leading characters were right.
Return a 2xx within 30 seconds of the request, and do the real work from a queue. A slower answer counts as a failed delivery.
The header can hold two signatures, such as v1=abc...,v1=def.... That happens for 24 hours after a secret rotation, when each delivery is signed with the new and the previous secret. A rotation with immediate=true has no overlap. A handler that reads one signature rejects every delivery in that window.
The handler
The first four examples read the raw body, enforce the 300-second window and compare in constant time. The shell script is for checking a captured delivery by hand. Set the secret in WEBHOOK_SECRET.
// Node 18+, Express. express.raw() gives req.body as a Buffer.
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.WEBHOOK_SECRET; // whsec_...
app.post("/webhooks/anton", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.header("X-Webhook-Timestamp");
const signatures = (req.header("X-Webhook-Signature") || "")
.split(",")
.map((s) => s.trim().replace(/^v1=/, ""))
.filter(Boolean);
if (!timestamp || signatures.length === 0) return res.status(400).send("missing headers");
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Math.floor(Date.now() / 1000) - ts) > 300) {
return res.status(400).send("stale timestamp");
}
// Hash the raw bytes. Decoding them to a string first can change them.
const expected = crypto
.createHmac("sha256", SECRET)
.update(Buffer.concat([Buffer.from(`${timestamp}.`), req.body]))
.digest();
const valid = signatures.some((sig) => {
const actual = Buffer.from(sig, "hex");
return actual.length === expected.length && crypto.timingSafeEqual(expected, actual);
});
if (!valid) return res.status(400).send("invalid signature");
// Queue req.body for a worker, then acknowledge.
res.status(200).send();
});When it fails
If every delivery is rejected, check these first.
- A parsed body. The framework read the JSON before your handler did. Mount the raw reader on this route only.
- A body that was changed on the way. A proxy that adds a trailing newline or changes the encoding invalidates the signature.
- The wrong secret. Rotation issues a new
whsec_value. During the 24-hour window the header carries a signature for each secret, and after it only the new one. - A clock that has drifted. Every delivery looks stale. Check your server's time before you check anything else.
==orstrcmp. It works in a test and leaks timing in production. Usecrypto.timingSafeEqual,hmac.compare_digest,hash_equalsorhmac.Equal.
The headers Anton sent, signature included, are kept with each delivery attempt. GET /v1/webhooks/{id}/deliveries returns them next to what your server answered, so you can recompute the signature from a real attempt.
A verified delivery can still arrive twice. The signature proves who sent it, not that you have not seen it. Deduplicate on X-Webhook-ID.