Webhook guide

Setup

1. Provide a Webhook URL

Pass webhook_url when creating resources via API V2:

Entity Validation:

POST /api/v2/entity_validations
{
  "tin": "77092317-4",
  "country": "CL",
  "webhook_url": "https://your-server.com/webhooks"
}

With Information Request:

POST /api/v2/entity_validations
{
  "tin": "77092317-4",
  "country": "CL",
  "webhook_url": "https://your-server.com/webhooks",
  "information_request": {
    "template_id": "irt_xxx",
    "webhook_url": "https://your-server.com/irq-webhook"  // Optional, separate URL for Information Request
  }
}

Standalone Information Request:

POST /api/v2/information_requests
{
  "entity_validation_id": "evl_xxx",
  "template_id": "irt_xxx",
  "webhook_url": "https://your-server.com/webhooks"
}

Note: Webhook URLs must use HTTPS.

2. Authentication (Optional)

Configure a Bearer token in your organization settings. This has to be done through support.
When set up all webhooks will include:

Authorization: Bearer <your-token>

Webhook Events

Data Source Run Batch Events

Sent to the webhook_url on the Entity Validation or batch.

Event	When Triggered
`data_source_run_batch.ready`	All data source runs in a batch completed successfully
`data_source_run_batch.data_source_run.ready`	Individual data source run completed
`data_source_run_batch.consolidated_report_ready`	Consolidated PDF report is generated and available

Information Request Events

Sent to the webhook_url on the Information Request (if configured separately).

Event	When Triggered
`information_request.all_items_collected`	All requestable items have been submitted by the recipient
`information_request.assignment.updated`	A reviewer's assignment status changed
`information_request.status_updated`	The Information Request status changed
`information_request.analysis_success`	AI analysis completed successfully

Webhook Payload

All webhooks are sent as POST requests with Content-Type: application/json.

Batch Ready / Consolidated Report Ready

{
  "type": "data_source_run_batch.ready",
  "data_source_run_batch": {
    "id": "dsrb_5a6141dec2bc384e",
    "runs_succeeded": true,
    "entity_validation_id": "evl_xxx",
    "information_request_id": "irq_xxx",  // null if not linked to Information Request
    "parent_batch_id": null,
    "execution_type": "direct",
    "request_type": "normal",
    "created_at": "2024-01-15T19:48:18.056Z",
    "updated_at": "2024-01-15T19:50:22.000Z",
    "consolidated_report_url": "https://...",  // Available after report generation
    "webhook": {
      "id": "wbh_xxx",
      "webhook_url": "https://your-server.com/webhooks",
      "started_at": "2024-01-15T19:50:22.000Z",
      "succeeded_at": null,
      "failed_at": null,
      "created_at": "2024-01-15T19:48:18.056Z"
    },
    "data_source_runs": [
      {
        "id": "dsr_xxx",
        "type": "cl/tax_situation_search",
        "status": "succeeded",
        "created_at": "2024-01-15T19:48:18.056Z",
        "succeeded_at": "2024-01-15T19:49:00.000Z"
      }
    ],
    "raised_alerts": []
  }
}

Individual Data Source Run Ready

Sent when each individual data source run completes (before the full batch is done).

{
  "type": "data_source_run_batch.data_source_run.ready",
  "data_source_run": {
    "id": "dsr_5ac79b8b3ecfaacf",
    "type": "cl/tax_situation_search",
    "entity_validation_id": "evl_xxx",
    "data_source_run_batch_id": "dsrb_xxx",
    "created_at": "2024-01-15T19:48:18.056Z",
    "succeeded_at": "2024-01-15T19:49:00.000Z",
    "status": "succeeded"
  }
}

Possible status values:

succeeded - Run completed successfully
created - Run is still in progress
temporary_error - Temporary failure (will retry)
definitive_error - Permanent failure
missing_input_data - Waiting for required input

Information Request Events

{
  "type": "information_request.all_items_collected",
  "information_request": {
    "id": "irq_5a6141dec2bc384e",
    "name": "KYC Request",
    "status": "pending",
    "entity_validation_id": "evl_xxx",
    "template_id": "irt_xxx",
    "recipient_url": "https://...",
    "consolidated_report_url": null,
    "requestable_items": [...],
    "data_source_run_batch": {...},
    "assignments": [...],
    ...
  }
}

The full payload includes requestable_items, data_source_run_batch, assignments, information_sheet, and analysis_chat. See the API reference for complete schema.

Key Fields

Field	Description
`type`	Event type (see table above)
`data_source_run_batch.id`	Unique batch identifier
`runs_succeeded`	`true` if all runs completed successfully
`entity_validation_id`	Parent entity validation
`information_request_id`	Associated Information Request (if any)
`consolidated_report_url`	URL to download the PDF report (when available)
`data_source_runs`	Array of individual run results
`raised_alerts`	Alerts triggered by rule engine

Retry Behavior

Failed webhooks (non-200 responses) are retried up to 20 times with exponential backoff.

Event Flow

1. Entity Validation / Information Request created
   └── Data source runs start
       └── Individual runs complete
           └── data_source_run_batch.data_source_run.ready (per run)
       └── ALL runs complete
           └── data_source_run_batch.ready
           └── Report generation starts
               └── data_source_run_batch.consolidated_report_ready

Best Practices

Always respond with HTTP 200 to acknowledge receipt
Process asynchronously - don't block the response
Use idempotency - you may receive duplicate webhooks on retries
Store data_source_run_batch.id to correlate events
Check runs_succeeded before processing results