# 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.

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](https://www.standardwebhooks.com/), so its libraries verify our deliveries directly. Pass the raw body, not parsed JSON.

```js
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.

```js
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.

## Related

- [Webhooks](https://brokerandagent.com/developers/webhooks)
- [Webhook events](https://brokerandagent.com/developers/webhooks/events)

---

Source: https://brokerandagent.com/developers/webhooks/verify
