Verifying signatures - Instant Compliance API

Every delivery carries three headers:

Header	Value
`IC-Signature`	Lowercase hex HMAC-SHA256 over `{timestamp}.{raw body}`.
`IC-Timestamp`	Unix time in seconds when we signed the request.
`IC-Event-Id`	The event’s unique id (matches `id` in the body). Use it to dedupe.

The algorithm

Read the raw request body as bytes/text — do not re-serialise the parsed JSON, or whitespace/key-order differences will break the signature.
Reject the request if now - IC-Timestamp is greater than 300 seconds (5-minute replay window).
Compute HMAC_SHA256(secret, "{IC-Timestamp}.{raw body}") as hex.
Compare it to IC-Signature with a constant-time comparison.
Only if it matches, parse the body and dedupe on IC-Event-Id.

The secret is the whsec_… value shown once when you created the endpoint.

Node.js example

import crypto from 'node:crypto';

// `rawBody` is the exact bytes/string we POSTed — capture it before JSON parsing.
export function verifyWebhook(rawBody, headers, secret) {
  const signature = headers['ic-signature'];
  const timestamp = headers['ic-timestamp'];
  if (!signature || !timestamp) return false;

  // 5-minute replay window.
  const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(ageSeconds) || ageSeconds > 300) return false;

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

  // Constant-time compare — bail if lengths differ (timingSafeEqual throws otherwise).
  const a = Buffer.from(signature, 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Verify the signature on the raw body, before parsing. Frameworks that auto-parse JSON (Express express.json(), Next.js route handlers) may not expose the raw bytes by default — configure a raw-body reader for your webhook route.

If verification fails

Return a 4xx and do nothing else. A failed signature means the request did not come from us (or was tampered with) — never process it. If legitimate events start failing verification, confirm you’re using the right endpoint’s secret and signing over the raw body.