Webhooks in sanctions.io
Webhooks in sanctions.io empower your applications to receive real-time notifications about various events, such as batch screening results or account updates. To start receiving webhook events, register your webhook endpoint.
Use Case Example: You might want to receive notifications for batch_query-processed events.
When an event occurs, sanctions.io generates a webhook-event object, which is then sent to your registered webhook endpoint.
Example 1: A search_result-processed event is triggered when a new search is completed. Example 2: For a new BatchQuery, multiple search_result-processed events and a final batch_query-processed event will be triggered.
All webhook-event objects share a common structure:
- object_type
- action
- data: The complete data payload related to the object
object_type | actions | Allows Sandbox | Description |
api_token | created, deleted, updated | No | Token lifecycle events |
batch_query | processed | Yes | BatchQuery processing completion |
search_result | processed | Yes | Individual search completion |
company | updated | No | Company data updates |
company_config | updated | No | Configuration updates |
Note: More webhook actions will be added in the future.
Your webhook endpoint should:
- Handle HTTPS POST requests with a JSON payload 'application/json'
- Return a 2xx response quickly.
- Include any required tokens or security measures in the URL.
Example: https://descentllc.com/sanctions-webhook?token=this-token
Note: We cannot accommodate special cases like unique headers or payload types.
sanctions.io will send the following security headers to your endpoint:
- x-sanctions-origin
- x-sanctions-api-token: An obfuscated version of your default token
- x-sanctions-sandbox: Set when the event is triggered by a sandbox token
Events triggered by sandbox tokens will be sent to sandbox_webhook_url instead of the production webhook_url.
Note: You can differentiate between sandbox and production events using the x-sanctions-sandbox header.