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