Webhooks KYB de la API: eventos, payloads y firma HMAC

Los webhooks de KYB de Didit avisan a tu backend cuando una sesión de verificación de empresas cambia de estado o cuando un revisor o el registro modifican los datos de la sesión. Las entidades de empresa tienen sus propios eventos. Suscríbete a los eventos que te interesen mediante la API de destinos de webhook o desde la Business Console.

Catálogo de eventos

Los eventos de sesión son comunes a las sesiones de usuario y de empresa. El campo session_kind del payload indica a qué tipo de sesión se refiere el evento. Los eventos de entidad son independientes de los eventos de sesión.

Eventos de sesión

Evento	Cuándo se envía
`status.updated`	Cambió el estado de una sesión. En las sesiones de Verificación de empresas (KYB), el payload incluye `session_kind: "business"`. Es el evento que debes seguir para conocer el progreso.
`data.updated`	Un revisor editó los datos del registro, omitió o regeneró las personas clave en la consola, o el registro notificó un cambio (cuando la monitorización del registro está disponible). El campo `trigger` indica cuál de estos casos se produjo.

data.updated no se envía cuando el solicitante sube un documento o envía las personas clave, ni cuando termina un reanálisis AML. Usa status.updated o consulta la decisión de la sesión para seguir ese progreso.

Eventos de entidad de empresa

Evento	Cuándo se envía
`business.status.updated`	Cambió el estado de la entidad de empresa vinculada (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	Cambiaron los campos del perfil o los contadores agregados de la entidad de empresa.

Suscríbete a cualquier combinación de eventos en tu destino de webhook. Consulta los webhooks de entidades para ver la referencia completa de eventos de entidades de empresa y de usuario.

Estructura del payload

Los webhooks de sesión usan un payload plano, sin el contenedor data. El sobre, los encabezados de firma y todos los campos comunes se documentan en la referencia de webhooks. Una sesión KYB añade estos campos:

Campo	Tipo	Descripción
`session_kind`	`"business"`	Permite que un handler genérico distinga entre KYC y KYB.
`business_session_id`	`uuid`	Igual a `session_id`.
`vendor_business_id`	string	Tu identificador de la entidad empresarial, si lo indicaste al crear la sesión.
`status`	string	La etiqueta exacta, por ejemplo `"In Progress"`, `"Approved"` o `"Awaiting User"`. Consulta los estados.
`trigger`	string	Opcional. Motivo por el que se envió el webhook. En `data.updated` para KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` o `"kyb_registry_change"`.
`decision`	object	Presente cuando `status` es `Approved`, `Declined`, `In Review` o `Abandoned`. Tiene la misma estructura que `GET /v3/session/{id}/decision/`; consulta el esquema de respuesta.
`resubmit_info`	object	Presente cuando `status` es `Resubmitted`.

`status.updated` para una sesión KYB

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

El bloque decision incluye registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] y el resto de arrays de KYB.

`data.updated` para una sesión KYB

data.updated usa el mismo sobre plano que status.updated, además de un trigger que indica por qué se envió. Cuando el estado de la sesión es Approved, Declined, In Review o Abandoned, también incluye la decision actual. Vuelve a consultar la decisión para ver qué cambió. El payload no incluye una lista changed_fields.

`business.status.updated` y `business.data.updated`

Los eventos de entidad también son planos. Incluyen vendor_business_id, vendor_data, status (ACTIVE, FLAGGED o BLOCKED) y created_at. business.status.updated añade previous_status. business.data.updated añade changed_fields y un mapa changes con la forma { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

Verificación de firma

Cada webhook se firma con HMAC-SHA256 usando el secreto compartido de tu destino. Verifica el cuerpo sin procesar de la solicitud con el encabezado X-Signature-V2 (recomendado) y rechaza las entregas cuyo X-Timestamp tenga más de 300 segundos de antigüedad. La referencia de webhooks enumera todos los encabezados de firma, el periodo de solapamiento durante la rotación del secreto de firma y ejemplos de código.

Política de reintentos

Una respuesta 5xx o 404, un tiempo de espera agotado o un fallo de conexión provocan hasta 2 reintentos, tras aproximadamente 1 minuto y aproximadamente 4 minutos; después, la entrega se descarta.
Las demás respuestas 4xx y 3xx no se reintentan.
Cada reintento conserva el mismo event_id, así que úsalo para eliminar duplicados.
Puedes reenviar una entrega desde el registro de entregas del destino. La referencia de webhooks describe la política completa.

Suscripción

Suscríbete a los eventos que te interesen en un destino de webhook:

curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated"
    ]
  }'

Filtra las sesiones de empresa en tu sistema comprobando session_kind === "business" dentro de los eventos status.updated y data.updated.

Próximos pasos

Referencia de webhooks

Destinos, firma, reintentos y patrones habituales.

Estados

Referencia de estados de sesiones y funciones.

Esquema de respuesta

Cómo interpretar el payload de decisión de KYB.

Primeros pasos

Funciones

Perfiles de empresa

Referencia

Consola

Webhooks KYB de la API: eventos, payloads y firma HMAC

Catálogo de eventos

Eventos de sesión

Eventos de entidad de empresa

Estructura del payload

`status.updated` para una sesión KYB

`data.updated` para una sesión KYB

`business.status.updated` y `business.data.updated`

Verificación de firma

Política de reintentos

Suscripción

Próximos pasos

Referencia de webhooks

Estados

Esquema de respuesta

​Catálogo de eventos

​Eventos de sesión

​Eventos de entidad de empresa

​Estructura del payload

​status.updated para una sesión KYB

​data.updated para una sesión KYB

​business.status.updated y business.data.updated

​Verificación de firma

​Política de reintentos

​Suscripción

​Próximos pasos

Referencia de webhooks

Estados

Esquema de respuesta

Catálogo de eventos

Eventos de sesión

Eventos de entidad de empresa

Estructura del payload

`status.updated` para una sesión KYB

`data.updated` para una sesión KYB

`business.status.updated` y `business.data.updated`

Verificación de firma

Política de reintentos

Suscripción

Próximos pasos