Webhooks.

1. Read the X-Alethia-Signature header and split it on commas into t=<unix seconds> and one or more v1=<hex> values.
2. Take the RAW request body bytes exactly as received, and build the signed string: t, a full stop, then the body.
3. Compute HMAC-SHA256 over that string using the subscription's signingSecret (whsec_…) as the key and hex-encode it.
4. Compare against each v1 value in constant time; accept the delivery if any matches.
5. Reject the delivery if t is more than five minutes (300 seconds) from your own clock, in either direction.

const crypto = require("node:crypto");

const TOLERANCE_SECONDS = 300; // reject anything older (or newer) than 5 minutes

// X-Alethia-Signature: t=1760000000,v1=9f2c…
function isValidSignature(rawBody, signatureHeader, signingSecret) {
  const parts = Object.fromEntries(
    (signatureHeader || "").split(",").map((part) => part.trim().split("=")),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false; // replay guard
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(t + "." + rawBody) // the RAW bytes, before any JSON.parse
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Replay protection

• The timestamp is part of the signed string, so an attacker cannot change t without invalidating the signature; checking t against a tolerance is what defeats a replayed capture. Five minutes is the recommended tolerance; keep your server clock synchronised (NTP).
• t is the time of each delivery attempt. A retry is the same body with a fresh t and a fresh signature, so a tolerance window never rejects a legitimate retry.
• A tolerance does not by itself stop a replay inside the window. To reject a replay, key on signed data only: for entity.* events store the envelope id and ignore repeats; for every other event, AFTER the signature verifies, compute a replay key from the verified values, not from the header text: SHA-256 of the exact signed string <t>.<raw body>, with t as the parsed number. Store it and reject a repeat. Never key on the raw X-Alethia-Signature string: the same valid signature can be resent with its fields reordered, extra spaces or upper-case hex, which still verifies but is a different string. Keep each key for at least the signature tolerance (five minutes if you use the recommended tolerance), since an older capture already fails the t check. entity.* events may use either their envelope id or this key.
• X-Alethia-Delivery-Id is NOT authenticated and must never be your replay check: anyone holding a captured request can change it without invalidating the signature. Use it only to skip work for a legitimate retry you have already processed (a retry has a fresh t, so its signature differs, but its delivery id is the same).
• Never log or echo the signing secret; compare signatures in constant time.

Legacy X-Tithe-Signature

Legacy, kept for compatibility: HMAC-SHA256 over the body alone, hex, prefixed: sha256=<hex digest>. It carries no timestamp, so it cannot detect replay; prefer X-Alethia-Signature.

// Legacy X-Tithe-Signature: sha256=<hex> — body only, no timestamp, no replay guard.
function isValidLegacySignature(rawBody, signatureHeader, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = (signatureHeader || "").replace(/^sha256=/, "");
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}