Verifying Webhook Signatures

Verifying Webhook Signatures

Kinexa signs every webhook so you can trust the payload genuinely came from us.

The Signature Header

Each webhook request includes:

X-Kinexa-Signature: t=1717689600,v1=5257a8...

How to Verify

1. Get your webhook signing secret from Settings → Developer → Webhooks
2. Build the signed payload: {timestamp}.{raw_body}
3. Compute an HMAC-SHA256 using your secret
4. Compare it to the v1 value using a constant-time comparison

Example (Node.js)

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const [t, sig] = header.split(",").map(p => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(sig));
}

Reject Stale Events

Reject requests whose timestamp is older than ~5 minutes to prevent replay attacks.

Always Return 200 Fast

Acknowledge quickly with HTTP 200, then process asynchronously. Kinexa retries failed deliveries with backoff.