One HMAC over the timestamp and the raw body, and nothing else.

The header, by example

A delivery looks like this. The two headers are the only part you have to inspect before trusting the body.

POST /your-endpoint HTTP/1.1
content-type: application/json
x-freelyform-event: submission.created
x-freelyform-signature: t=1762905600,v1=6f1d3c...c9ab

Verifying it without breaking it

The single most common failure is verifying after parsing. If you read the body as JSON and then stringify it again to compute the digest, key order and whitespace change, the digest differs, and every delivery looks forged. Keep the raw text.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((piece) => piece.split("=") as [string, string]),
  );
  const timestamp = Number(parts.t);
  const provided = parts.v1;
  if (!Number.isFinite(timestamp) || !provided) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Two details are worth keeping even in a five-line version: the tolerance check, and the constant-time comparison. Without the first, a captured request is valid forever. Without the second, response timing leaks how much of the expected digest you guessed right.

What the signature does not cover

The event name lives in x-freelyform-event and is not part of the signed string. That is fine as long as you do not route on the header alone: route on the event field inside the verified body. If you must branch on the header — for logging or metrics — do it after verification, never before.

Why bother, when a random URL would do

A secret path stops someone who guesses URLs. It does not stop a leaked URL, and it gives you nothing to distinguish a genuine retry from a forged one. A signature makes the receiver's decision explicit and cheap: correct digest, correct secret, recent timestamp, act on it; otherwise reject and let the retry log speak for itself.