Webhooks

{timestamp}.{raw_body}

const crypto = require("crypto");

function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  // "t=1724500000,v1=abc123..."
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("="))
  );

  const timestamp = Number(parts.t);
  if (!timestamp) return false;

  // Reject anything outside the tolerance window. This is what stops a captured
  // request being replayed against you indefinitely.
  const ageSeconds = Math.abs(Date.now() / 1000 - timestamp);
  if (ageSeconds > toleranceSeconds) return false;

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

  // Constant-time comparison — never use ===
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

{
  "id": "9f2b6c4d8e1a4f7b9c3d5e6f7a8b9c0d",
  "type": "TransactionStatusChanged",
  "created": 1788063247,
  "livemode": true,
  "data": {
    "TransactionId": "b81d47c0-16e2-4f39-a0d5-77c9e3f21b64",
    "PreviousStatus": "Pending",
    "CurrentStatus": "Completed",
    "TraceId": "8f3a1c22d4b64e0fa1c9b7e5d2f30a41",
    "...": "..."
  }
}