Webhooks

Headers we send

• Content-Type: application/json
• X-Ideaudit-Event — one of audit.finalized, audit.outcome.recorded, entity.created.
• X-Ideaudit-Signature: sha256=<hex> — see below.
• X-Ideaudit-Endpoint: <uuid> — your endpoint id, for routing on multi-endpoint receivers.

Verifying signatures (Node)

The signature is HMAC-SHA256(secret, raw_request_body) as a hex string, prefixed with sha256=. Verify against the raw bytes of the body — never the re-serialized JSON.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret: string, signatureHeader: string, rawBody: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Verifying signatures (Python)

import hmac, hashlib

def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Test events

The dashboard's “Test” button uses your most recent finalized audit's id (or zero-UUID if you have none) and adds isTest: true to the payload. Branch on it in your receiver to skip side-effects.

Auto-disable

After 5 consecutive non-2xx responses we flip active = false and surface the endpoint with an Auto-disabled badge. Click Re-enable on Settings → Webhooks once you've fixed the receiver. Recent delivery history (status + response body) is shown in an expandable panel per endpoint.