Webhook Guide

Setup

1. Provide a Webhook URL

When creating resources via API V2, include the webhook_url parameter:

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"
  }
}

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 through organization settings (via support). When configured, all webhooks include:

Authorization: Bearer <your-token>

Webhook Events

Entity Validation Events

Sent to the webhook URL on Entity Validation:

Event	Trigger
`entity_validation.stakeholder.created`	Stakeholders added to entity validation

Data Source Run Batch Events

Sent to the webhook URL on Entity Validation or batch:

Event	Trigger
`data_source_run_batch.ready`	All runs completed successfully
`data_source_run_batch.data_source_run.ready`	Individual run completed
`data_source_run_batch.consolidated_report_ready`	PDF report generated

Information Request Events

Sent to the webhook URL on Information Request (if separately configured):

Event	Trigger
`information_request.all_items_collected`	All items submitted by recipient
`information_request.assignment.updated`	Reviewer assignment status changed
`information_request.status_updated`	Status changed
`information_request.analysis_success`	AI analysis completed

Webhook Payload

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

Entity Validation Events Payload

{
  "type": "entity_validation.stakeholder.created",
  "stakeholder": {
    "id": "evl_e63adcdf5c702350",
    "tin": "76613324-k",
    "display_name": "Sociedad Comercial Bon Cas Limitada",
    "name": "Sociedad Comercial Bon Cas Limitada",
    "surname": "",
    "category": "business",
    "country": "CL",
    "status": "created",
    "created_at": "2026-02-02T15:51:12.105Z",
    "information_requests": [
      {
        "id": "irq_bc8cf77370892cf1",
        "name": "Nuevo cliente",
        "created_at": "2026-02-02T15:51:12.188Z",
        "recipient_url": "https://..."
      }
    ],
    "data_source_run_batches": [
      {
        "id": "dsrb_75eae47d0060cf5d",
        "runs_succeeded": true,
        "entity_validation_id": "evl_e63adcdf5c702350",
        "information_request_id": "irq_bc8cf77370892cf1",
        "execution_type": "direct",
        "request_type": "normal",
        "created_at": "2026-02-02T15:51:12.115Z",
        "updated_at": "2026-02-02T15:54:34.166Z",
        "consolidated_report_url": "https://..."
      }
    ],
    "related_entities": [
      {
        "id": "evl_557f33434aebd60e",
        "tin": "20025804-5",
        "country": "CL",
        "display_name": "Alejandro Ignacio Castillo Valera",
        "name": "Alejandro Ignacio",
        "surname": "Castillo Valera",
        "category": "person",
        "risk_level": null
      },
      {
        "id": "evl_8e953696cbe06919",
        "tin": "19246648-2",
        "country": "CL",
        "display_name": "Felipe Dominguez Claro",
        "name": "Felipe",
        "surname": "Dominguez Claro",
        "category": "person",
        "risk_level": null
      }
    ],
    "latest_raised_alerts": [],
    "latest_data_source_runs": [
      {
        "id": "dsr_c83d588a5c0bcc2f",
        "type": "cl/bankruptcy_bulletins_search",
        "entity_validation_id": "evl_e63adcdf5c702350",
        "data_source_run_batch_id": "dsrb_75eae47d0060cf5d",
        "created_at": "2026-02-02T15:51:12.127Z",
        "succeeded_at": "2026-02-02T15:51:12.506Z",
        "status": "succeeded",
        "data": {
          "id": "bbs_6bc2ce7c1f115d56",
          "bankruptcy_bulletins": {
            "count": 0,
            "records_url": "/api/v2/data_source_runs/dsr_c83d588a5c0bcc2f/records"
          }
        }
      }
    ]
  }
}

The stakeholder object contains the parent entity validation with its full data, including the newly created related_entities (the stakeholders that were just added).

Data Source Run Batch Events Payload

{
  "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",
    "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://...",
    "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 Events Payload

{
  "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 in progress
temporary_error - Temporary failure (will retry)
definitive_error - Permanent failure
missing_input_data - Waiting for required input

Information Request Events Payload

{
  "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": [...]
  }
}

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

Key Fields

Field	Description
`type`	Event type identifier
`data_source_run_batch.id`	Unique batch identifier
`runs_succeeded`	Boolean indicating overall success
`entity_validation_id`	Parent validation reference
`information_request_id`	Associated request (if any)
`consolidated_report_url`	PDF download URL when available
`data_source_runs`	Array of individual results
`raised_alerts`	Rule engine alerts
`related_entities`	Stakeholders linked to entity validation

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
   |
   +-- Stakeholders created (via societary data or API)
       |
       +-- entity_validation.stakeholder.created

Best Practices

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