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.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us