Verifying signatures

Every webhook Kua sends carries an X-Kua-Signature header. Verify it with your endpoint’s signing secret (whsec_…) before trusting the payload.

Headers

Header	Description
`X-Kua-Signature`	`t={unix_seconds},v1={hex_hmac}`
`X-Kua-Event-Type`	The event type, e.g. `payroll.disbursed`.
`X-Kua-Event-Id`	The event’s unique id (use it to dedupe).
`X-Kua-Delivery-Id`	This delivery attempt’s id.

How the signature is computed

Kua computes HMAC-SHA256(secret, "{t}.{raw_body}") and hex-encodes it as the v1 value, where t is the timestamp in the header and raw_body is the exact bytes of the request body.

Verify (Node.js)

import crypto from "node:crypto";

export function verifyKuaSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  // constant-time compare
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify against the raw request body, before any JSON parsing/re-serialization — re-encoding changes the bytes and breaks the signature.

Guard against replays

The t timestamp lets you reject stale deliveries — e.g. ignore anything older than a few minutes. Combined with deduping on X-Kua-Event-Id, this makes your handler safe against retries and replays.

Webhooks overview Event types & payload

⌘I

​Headers

​How the signature is computed

​Verify (Node.js)

​Guard against replays

Headers

How the signature is computed

Verify (Node.js)

Guard against replays