Webhooks

When you configure a webhook endpoint, Exclia pushes signed deliveries for three events: match_status_change (a monitored entity’s screening status changed), batch_completed, and list_update. Screening payloads carry only clear or potential_match with per-field evidence and provenance (list_version ids and retrieval dates) — never an automated “excluded” verdict.

Each delivery is a JSON body with headers Exclia-Webhook-Id (the delivery id), Exclia-Event-Type, and Exclia-Signature: t=<unixSeconds>,v1=<hex>.

Verifying a deliveryCopy Anchor Link

1. Read t and v1 from the Exclia-Signature header.
2. Reject the delivery if t is more than 5 minutes from your current time (replay protection).
3. Compute HMAC-SHA256(signingSecret, "<t>." + rawRequestBody) as lowercase hex — use the EXACT received bytes, before any JSON re-serialization.
4. Constant-time compare your hex digest to v1. If they differ, the payload was tampered with or signed with a different secret — discard it. Only on a match do you trust the event.
5. Respond 2xx to acknowledge. A non-2xx or timeout is retried with exponential backoff; every attempt is recorded in your delivery log, and you can replay any delivery from it.

Your signing secret is shown once when you register or rotate the endpoint. Rotate it if it leaks; the previous secret stops signing immediately.