Verifying webhook signatures

<timestamp>.<deliveryId>.<eventId>.<rawBody>

"signatures": {
  "header": "x-stableyard-signature",
  "timestampHeader": "x-stableyard-timestamp",
  "deliveryHeader": "x-stableyard-delivery",
  "eventHeader": "x-stableyard-event",
  "scheme": "hmac-sha256",
  "signedPayload": "<timestamp>.<deliveryId>.<eventId>.<rawBody>"
}

import crypto from "node:crypto";

const MAX_TIMESTAMP_SKEW_SECONDS = 300;

function requiredHeader(headers, name) {
  const value = headers[name];
  if (typeof value !== "string" || value.length === 0) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

export function verifyStableyardWebhook(rawBody, headers, signingSecret) {
  if (!Buffer.isBuffer(rawBody)) throw new Error("rawBody must be a Buffer");

  const signature = requiredHeader(headers, "x-stableyard-signature");
  const timestampHeader = requiredHeader(headers, "x-stableyard-timestamp");
  const deliveryId = requiredHeader(headers, "x-stableyard-delivery");
  const eventId = requiredHeader(headers, "x-stableyard-event-id");
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/i.exec(signature);
  if (!match) throw new Error("Malformed webhook signature");

  const [, signedTimestamp, providedHex] = match;
  if (signedTimestamp !== timestampHeader) {
    throw new Error("Webhook timestamp mismatch");
  }

  const timestamp = Number(signedTimestamp);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isSafeInteger(timestamp) || Math.abs(now - timestamp) > MAX_TIMESTAMP_SKEW_SECONDS) {
    throw new Error("Webhook timestamp outside tolerance");
  }

  const prefix = Buffer.from(`${signedTimestamp}.${deliveryId}.${eventId}.`, "utf8");
  const payload = Buffer.concat([prefix, rawBody]);
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(payload)
    .digest();
  const provided = Buffer.from(providedHex, "hex");

  if (provided.length !== expected.length || !crypto.timingSafeEqual(expected, provided)) {
    throw new Error("Invalid webhook signature");
  }

  return { deliveryId, eventId, timestamp };
}

curl -X POST https://staging-api-v2.stableyard.fi/v2/console/webhooks/webhook_123/rotate-secret \
  -u "$APP_ID:$APP_SECRET"

{
  "webhookEndpoint": { "id": "webhook_123", "status": "active" },
  "signingSecret": "whsec_…"
}