How to sign and verify a message with HMAC-SHA256 in Node.js

1import { createHmac, timingSafeEqual } from "node:crypto";
2 
3// Sender: HMAC-SHA256 over the exact bytes of the body, sent as "sha256=<hex>"
4export function sign(secret, rawBody) {
5  return "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
6}
7 
8// Receiver: recompute over the raw body and compare in constant time
9export function verify(secret, rawBody, header) {
10  const match = /^sha256=([0-9a-f]{64})$/i.exec(header ?? "");
11  if (!match) return false; // a missing or malformed header fails, it never skips the check
12  const expected = createHmac("sha256", secret).update(rawBody).digest();
13  return timingSafeEqual(Buffer.from(match[1], "hex"), expected); // 32 bytes each
14}
15 

1import { createServer } from "node:http";
2import { verify } from "./webhook.mjs";
3 
4const secret = process.env.WEBHOOK_SECRET;
5 
6createServer((req, res) => {
7  const chunks = [];
8  req.on("data", (chunk) => chunks.push(chunk));
9  req.on("end", () => {
10    const rawBody = Buffer.concat(chunks); // the bytes as received, before any JSON parsing
11    // Node.js lower-cases incoming header names
12    if (!verify(secret, rawBody, req.headers["x-hub-signature-256"])) {
13      res.writeHead(401).end("bad signature\n");
14      return;
15    }
16    const event = JSON.parse(rawBody);
17    res.end(`accepted ${event.action} #${event.number}\n`);
18  });
19}).listen(8080);
20 

How it works

1. createHmac("sha256", secret).update(rawBody).digest("hex") is the whole signature: 64 hex digits, prefixed with sha256= as GitHub, and many providers after it, send it.
2. The receiver recomputes the MAC over the same bytes and compares the two with timingSafeEqual, whose running time does not depend on how many leading bytes match — === on strings returns at the first difference.
3. The regular expression accepts exactly sha256= plus 64 hex digits, so a missing, truncated or garbled header fails before any comparison, and timingSafeEqual always gets two 32-byte buffers.
4. The server collects the request chunks into one Buffer and verifies that, then parses JSON. The run shows GitHub's example (Hello, World! with the secret It's a Secret to Everybody) giving sha256=757107ea…3e17, and every altered input failing.
5. Keep the secret out of the code: the server reads it from WEBHOOK_SECRET.

Gotchas

• timingSafeEqual throws ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH when the two buffers differ in length, so a short header crashes a handler that calls it unchecked. Validate the format first, as the regular expression does.
• Buffer.from(hex, "hex") stops silently at the first character that is not hex: Buffer.from("75zz07", "hex") is the single byte <Buffer 75>. Never decode a header without checking it is all hex digits.
• The MAC covers bytes, not JSON. The same event re-serialized with JSON.stringify(JSON.parse(body)) loses the provider's whitespace and is rejected (401 above), so verify the raw body before any body-parser middleware turns it into an object.
• Node.js lower-cases incoming header names: read req.headers["x-hub-signature-256"], whatever case the sender used. A missing header must fail the request, as verify does, not skip the check.

Related recipes

• How to sign and verify a message with HMAC-SHA256 in WebCrypto
• How to sign and verify a message with HMAC-SHA256 in Python
• How to sign and verify a message with HMAC-SHA256 in Go
• How to sign and verify a message with HMAC-SHA256 with OpenSSL
• How to verify an ES256 JWT in Node.js