Webhooks in sanctions.io
Why Use Webhooks?
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.
Event Overview
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.
Webhook Event Object Structure
All webhook-event objects share a common structure:
- object_type
- action
- data: The complete data payload related to the object
Webhook Event Object Example:
{ "object_type": "company", "action": "updated", "data": { "name": "descent.llc", "vat": "12-234234B", "address_line_1": "422 Walnut St", "address_line_2": "5, 234", "city": "Sewickley", "postal_code": "15143", "state": "Pennsylvania", "country": "US", "company_config": { "weekly_consumption_report": false, "reports_recipients": [], "web-hook_url": "https://descentllc.com/sanctions-webhook", "sandbox_web-hook_url": null } } }
Available Webhook Events
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.
Setting Up Your Webhook Endpoint
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.
Security Headers
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
Sandbox Webhook Events
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.