Webhooks

• Verify the raw request body before parsing JSON.
• Compute HMAC-SHA256(signingSecret, timestamp + "." + rawBody) and compare it to the v1 signature with a constant-time comparison.
• Reject stale timestamps. Five minutes is a reasonable default.
• Treat MediaCaption-Event-Id as an idempotency key because retries can send the same event more than once.

MediaCaption-Event-Id: evt_...
MediaCaption-Timestamp: 1778493622
MediaCaption-Signature: v1=hex_hmac_sha256

signed_payload = "{timestamp}.{raw_request_body}"

import crypto from "node:crypto";

function verifyMediaCaptionSignature({
  rawBody,
  signatureHeader,
  timestampHeader,
  signingSecret,
}) {
  if (!signatureHeader || !timestampHeader) return false;

  const timestamp = Number(timestampHeader);
  if (!Number.isInteger(timestamp)) return false;

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 5 * 60) return false;

  const [version, signature] = signatureHeader.split("=");
  if (version !== "v1" || !/^[0-9a-f]{64}$/i.test(signature ?? "")) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest();
  const received = Buffer.from(signature, "hex");

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}