# Verify webhook signatures

> Check every Tamr webhook's HMAC-SHA256 signature on the raw body before trusting it, with a Standard Webhooks library or a few lines of Node.

Source: https://tamr.link/docs/webhooks/verify-signatures

Check every delivery before you trust it. Verify the signature on the **raw body** exactly as it arrived (parsing and re-serialising the JSON changes the bytes), and refuse a timestamp more than 5 minutes from your clock, so an old delivery can't be replayed.

## How Tamr signs

`webhook-signature` is `v1,` followed by the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with the secret's bytes: the base64 after `whsec_`. While a secret is being rotated there are two signatures separated by a space; one match is enough.

## With a Standard Webhooks library

There are libraries for Node, Python, Go, Ruby, PHP, Java, Kotlin, C# and Rust. In Node:

verify.js:

```js
import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.TAMR_WEBHOOK_SECRET); // "whsec_…"
// Throws on a bad signature or an old timestamp.
const event = wh.verify(rawBody, {
	"webhook-id": req.headers["webhook-id"],
	"webhook-timestamp": req.headers["webhook-timestamp"],
	"webhook-signature": req.headers["webhook-signature"],
});
```

## With nothing but Node's crypto

The same steps work in any language with HMAC-SHA256. Tamr's own tests run this exact function against deliveries signed the way Tamr's worker signs them, so it can't drift from the real thing.

verify-tamr-webhook.js:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

/** Checks a Tamr webhook and returns its event, or throws. */
export function verifyTamrWebhook(secret, headers, rawBody) {
	const id = headers["webhook-id"];
	const timestamp = headers["webhook-timestamp"];
	const signatures = headers["webhook-signature"];
	if (!id || !timestamp || !signatures) {
		throw new Error("Missing webhook headers");
	}
	const age = Math.abs(Date.now() / 1000 - Number(timestamp));
	if (!(age <= 300)) {
		throw new Error("Webhook timestamp too far from now");
	}
	const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
	const expected = createHmac("sha256", key)
		.update(`${id}.${timestamp}.${rawBody}`)
		.digest();
	const matches = signatures.split(" ").some((part) => {
		const [version, signature = ""] = part.split(",");
		const given = Buffer.from(signature, "base64");
		return (
			version === "v1" &&
			given.length === expected.length &&
			timingSafeEqual(given, expected)
		);
	});
	if (!matches) {
		throw new Error("Bad webhook signature");
	}
	return JSON.parse(rawBody);
}
```

> **Read the raw body**
>
> Most frameworks parse JSON before your handler runs. Ask yours for the raw bytes on this route (in Express, `express.raw({ type: "application/json" })`), verify them, then parse.

## Then

Answer with a 2xx within 15 seconds and do the work afterwards, and handle each `webhook-id` once. See [Retries and answering](https://tamr.link/docs/webhooks/retries).
