Verify webhook signatures

Check that a webhook really came from Broker & Agent, with a Standard Webhooks library or by hand, and rotate the secret without dropping events.

Updated Nov 11, 2026

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 whichever suits you.

Text
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, not parsed JSON.

JavaScript
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 wrong

The signature is an HMAC-SHA256 of ${webhook-id}.${webhook-timestamp}.${rawBody}, keyed with the base64 after whsec_, and base64-encoded.

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 about five minutes.

JavaScript
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)));
}
Warning

Verify against the raw request body. Parsing the JSON and serializing it again changes the bytes, and the signature won’t match.

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 the new one.

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 dropping an event.

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.