Verify webhook signatures
Check that a webhook really came from Broker & Agent, with a Standard Webhooks library or by hand, and rotate the secret
Anyone can POST to your URL. Before you act on a delivery, check its signature against your webhook’s whsec_… secret. Every delivery is signed two ways, so use
X-BA-Event: lead.created
X-BA-Delivery: wd_… (unique per event, deduplicate on it)
X-BA-Signature: t=1766361600,v1=8f3a…
webhook-id: wd_…
webhook-timestamp: 1766361600
webhook-signature: v1,K5oZ…With a Standard Webhooks library#
The webhook-* headers follow Standard Webhooks, so its libraries verify our deliveries directly. Pass the raw body,
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.BA_WEBHOOK_SECRET); // whsec_…
const event = wh.verify(rawBody, headers); // throws if the signature is wrongThe signature is an HMAC-SHA256 of ${webhook-id}.${webhook-timestamp}.${rawBody}, keyed with the base64 after whsec_
By hand#
v1 in X-BA-Signature is an HMAC-SHA256 of ${t}.${rawBody}, keyed with the whole secret string and hex-encoded. Reject timestamps older than
const crypto = require('node:crypto');
function verify(secret, header, rawBody, toleranceSec = 300) {
const parts = header.split(',').map((p) => p.split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
// during a secret rotation there are two v1 values; either may match
return parts
.filter(([k]) => k === 'v1')
.some(([, v1]) => v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)));
}Verify against the raw request body. Parsing the JSON and serializing it again changes the bytes, and the
Rotating the secret#
POST /webhooks/{id}/rotate-secret returns a new secret, for the person who made the webhook. In Settings, the maker or an owner or admin can rotate it under Deliveries and signing secret; an owner or admin never sees
For the next 24 hours every delivery is signed with both the new and the old secret (two v1 values in X-BA-Signature), so you can switch your receiver over without
Related#
Something missing or wrong? Email support@brokerandagent.com and