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.

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

Then

Answer with a 2xx within 15 seconds and do the work afterwards, and handle each webhook-id once. See Retries and answering.