Practical guide
Sanctions monitoring alerts and webhooks: a reliable handoff
Build a reliable sanctions monitoring webhook workflow with signature checks, event deduplication, durable processing, evidence retrieval, and analyst follow-up.
On this page
A notification is a signal to process, not a decision
A webhook lets an application respond to a monitoring event. It does not prove that an identity is confirmed, that all sources completed, or that the linked investigation can be closed. Use the event reference to retrieve the documented record and route the next task.
The current SanctionsKit webhook documentation and OpenAPI contract define the actual event fields. Do not invent a generic “customer is safe” event.
Authenticate the original request bytes
Verify the webhook using the configured secret and the original raw body before parsing or acting on it. SanctionsKit signs the event ID, timestamp, and raw body together and provides `Webhook-Id`, `Webhook-Timestamp`, and `Webhook-Signature` headers. Use the documented timestamp tolerance and a constant-time signature comparison.
Parsing and then reserializing JSON can change the bytes and invalidate verification. Reject missing, malformed, stale, or invalid signatures rather than continuing with a partially trusted payload.
Make delivery safe to repeat
Treat repeated deliveries as the same event by its event ID. Persist a durable record or queue item before acknowledging receipt. Do not acknowledge success and then rely on in-memory work that disappears when the process restarts.
Event deduplication and screening idempotency are different controls. One prevents duplicate notification work; the other makes retries of the same screening operation safe.
Retrieve the record and preserve the outcome
Use an authorized server-side key to retrieve the linked retained record. Validate the response and handle missing, expired, unavailable, or failed results explicitly. A fetch failure must not create an empty match list or a no-match status.
The event may lead to a changed-evidence review, an incomplete-screening issue, or another documented monitoring action. Keep the operational issue separate from a confirmed identity conclusion.
Route work to an owner
Map the internal customer reference, monitor, screening, and case so the reviewer has the history. A notification should explain what changed and where the relevant evidence is, without emailing a complete identity document.
Acknowledge the monitoring item through its intended workflow and resolve the investigation separately. Track work that is waiting for evidence, legal assessment, or a failed source recovery.
Test the recovery paths
Test duplicate delivery, a valid event processed after a restart, invalid signatures, stale timestamps, a broken downstream queue, expired results, and source failures. Keep operational telemetry free of API keys and unnecessary personal data.
The monitoring operations guide explains the reconciliation checks that remain necessary even when webhook delivery is configured correctly.