Webhook Signing

Verify webhook signatures with HMAC-SHA256.

Webhook secrets use the format whsec_<64 hex chars>. KorClaw signs the raw JSON body with HMAC-SHA256.

Signature format

text

X-KorClaw-Signature: t=<unix_seconds>,v1=<hex_hmac>

The signed payload is {timestamp}.{raw_json_body}. Verification tolerance is 300 seconds (5 minutes).

Verification example

typescript

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(
  body: string,
  signature: string,
  secret: string,
  toleranceSec = 300,
): boolean {
  const parts = Object.fromEntries(
    signature.split(",").map((p) => p.split("=") as [string, string]),
  );
  const timestamp = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSec) return false;

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

  return timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}