> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Webhooks KYB de Didit para sesiones y empresas: disparadores, payloads y verificación de firma HMAC. Desde $2.00 por verificación, sin contratos.

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](https://docs.didit.me/es/management-api/webhook/list-destinations.md) 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](https://docs.didit.me/es/getting-started/kyb-registry-pricing.md) 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](https://docs.didit.me/es/sessions-api/retrieve-session.md) 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](https://docs.didit.me/es/entities/businesses/overview.md) 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](https://docs.didit.me/es/entities/webhooks.md) 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](https://docs.didit.me/es/integration/webhooks.md#estructura-del-payload).
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](https://docs.didit.me/es/business-verification/statuses.md). |
| `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/`](https://docs.didit.me/es/sessions-api/retrieve-session); consulta el [esquema de respuesta](https://docs.didit.me/es/business-verification/response-schema.md). |
| `resubmit_info` | object | Presente cuando `status` es `Resubmitted`. |

### `status.updated` para una sesión KYB

```json theme={null}
{
  "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 } }`.

```json theme={null}
{
  "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](https://docs.didit.me/es/integration/webhooks.md#verificación-de-firma) 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](https://docs.didit.me/es/integration/webhooks.md#política-de-reintentos) describe la política completa.

## Suscripción

Suscríbete a los eventos que te interesen en un [destino de webhook](https://docs.didit.me/es/management-api/webhook/create-destination.md):

```bash theme={null}
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

> [card] [Referencia de webhooks](https://docs.didit.me/es/integration/webhooks.md)
>
> Destinos, firma, reintentos y patrones habituales.

> [card] [Estados](https://docs.didit.me/es/business-verification/statuses.md)
>
> Referencia de estados de sesiones y funciones.

> [card] [Esquema de respuesta](https://docs.didit.me/es/business-verification/response-schema.md)
>
> Cómo interpretar el payload de decisión de KYB.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.