> ## 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.

# API de webhooks KYB: esdeveniments, payloads i signatura

> Webhooks KYB de Didit per a sessions i entitats d'empresa: activadors, payloads i signatura HMAC. Des de $2.00 per verificació, sense contractes.

Didit els webhooks de KYB informen el vostre backend quan una sessió de Verificació d'empreses canvia d'estat o quan un revisor o el registre canvien les seves dades.
Les entitats empresarials tenen els seus propis esdeveniments.
Subscriviu-vos als esdeveniments que us interessen mitjançant l'[API de destinacions del webhook](https://docs.didit.me/ca/management-api/webhook/list-destinations.md) o la Business Console.

## Catàleg d'esdeveniments

Els esdeveniments de sessió són compartits entre les sessions d'usuari i les sessions d'empresa.
El camp `session_kind` del payload indica a quin tipus de sessió es refereix l'esdeveniment.
Els esdeveniments a nivell d'entitat són independents dels esdeveniments a nivell de sessió.

### Esdeveniments a nivell de sessió

| Esdeveniment | Quan s'activa |
| - | - |
| `status.updated` | Ha canviat l'estat d'una sessió. Per a les sessions de Verificació d'empreses (KYB), el payload inclou `session_kind: "business"`. Aquest és l'esdeveniment que cal seguir per conèixer el progrés. |
| `data.updated` | Un revisor ha editat les dades del registre, ha omès o regenerat les persones clau a la consola, o el registre mercantil ha informat d'un canvi (quan el [monitoratge del registre mercantil](https://docs.didit.me/ca/getting-started/kyb-registry-pricing.md) està disponible). El camp `trigger` indica quin dels casos ha passat. |

`data.updated` no s'envia quan el sol·licitant puja un document o envia les persones clau, ni quan acaba un reescaneig AML.
Utilitzeu `status.updated` o [recupereu la decisió de la sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md) per seguir aquest progrés.

### Esdeveniments d'entitat empresarial

| Esdeveniment | Quan s'activa |
| - | - |
| `business.status.updated` | Ha canviat l'estat de la [entitat d'empresa](https://docs.didit.me/ca/entities/businesses/overview.md) vinculada (`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated` | Han canviat els camps del perfil de l'entitat d'empresa o els seus comptadors agregats. |

Subscriviu-vos a qualsevol combinació d'esdeveniments a la vostra destinació del webhook.
Consulteu [webhooks d'entitats](https://docs.didit.me/ca/entities/webhooks.md) per a la referència completa dels esdeveniments d'entitat d'empresa i d'usuari.

## Estructura del payload

Els webhooks de sessió utilitzen un payload pla, sense un contenidor `data`.
L'embolcall, les capçaleres de signatura i tots els camps compartits es documenten a la [referència de webhooks](https://docs.didit.me/ca/integration/webhooks.md#forma-del-payload).
Una sessió KYB afegeix aquests camps:

| Camp | Tipus | Descripció |
| - | - | - |
| `session_kind` | `"business"` | Permet que un controlador genèric distingeixi entre KYC i KYB. |
| `business_session_id` | `uuid` | Igual que `session_id`. |
| `vendor_business_id` | string | El vostre identificador de l'entitat d'empresa, quan s'ha indicat en crear la sessió. |
| `status` | string | L'etiqueta exacta, per exemple `"In Progress"`, `"Approved"` o `"Awaiting User"`. Consulteu els [estats](https://docs.didit.me/ca/business-verification/statuses.md). |
| `trigger` | string | Opcional. Motiu pel qual s'ha activat el webhook. En `data.updated` per a KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` o `"kyb_registry_change"`. |
| `decision` | object | Apareix quan `status` és `Approved`, `Declined`, `In Review` o `Abandoned`. Té la mateixa estructura que [`GET /v3/session/{id}/decision/`](https://docs.didit.me/ca/sessions-api/retrieve-session), consulteu l'[esquema de resposta](https://docs.didit.me/ca/business-verification/response-schema.md). |
| `resubmit_info` | object | Apareix quan `status` és `Resubmitted`. |

### `status.updated` per a una sessió 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 bloc `decision` conté `registry_checks[]`, `key_people_checks[]`, `document_verifications[]`, `aml_screenings[]` i les altres matrius de KYB.

### `data.updated` per a una sessió KYB

`data.updated` porta el mateix embolcall pla que `status.updated`, més un `trigger` que indica el motiu pel qual s'ha activat.
Quan l'estat de la sessió és `Approved`, `Declined`, `In Review` o `Abandoned`, també inclou la `decision` actual.
Torneu a consultar la decisió per veure què ha canviat.
El payload no té cap llista `changed_fields`.

### `business.status.updated` i `business.data.updated`

Els esdeveniments d'entitat també són plans.
Porten `vendor_business_id`, `vendor_data`, `status` (`ACTIVE`, `FLAGGED` o `BLOCKED`) i `created_at`.
`business.status.updated` afegeix `previous_status`.
`business.data.updated` afegeix `changed_fields` i un mapa `changes` de `{ 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ó de la signatura

Cada webhook es signa amb HMAC-SHA256 utilitzant el secret compartit de la vostra destinació.
Verifiqueu el cos de la sol·licitud sense processar amb la capçalera `X-Signature-V2` (recomanada) i rebutgeu els lliuraments amb una `X-Timestamp` de més de 300 segons d'antiguitat.
La [referència de webhooks](https://docs.didit.me/ca/integration/webhooks.md#verificació-de-la-signatura) enumera totes les capçaleres de signatura, el solapament en la rotació del secret de signatura i els exemples de codi.

## Política de reintents

* Una resposta `5xx` o `404`, un temps d'espera esgotat o un error de connexió activen fins a 2 reintents, al cap d'aproximadament 1 minut i aproximadament 4 minuts, i després el lliurament es descarta.
* Les altres respostes `4xx` i `3xx` no es reintenten.
* Cada reintent conserva el mateix `event_id`, de manera que cal deduplicar-los amb aquest camp.
* Podeu tornar a enviar un lliurament des del registre de lliuraments de la destinació. La [referència de webhooks](https://docs.didit.me/ca/integration/webhooks.md#política-de-reintents) conté la política completa.

## Subscripció

Subscriviu-vos als esdeveniments que us interessen en una [destinació del webhook](https://docs.didit.me/ca/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"
    ]
  }'
```

Filtreu les sessions d'empresa al vostre costat comprovant `session_kind === "business"` dins dels esdeveniments `status.updated` i `data.updated`.

## Següents passos

> [card] [Referència de webhooks](https://docs.didit.me/ca/integration/webhooks.md)
>
> Destinacions, signatura, reintents, patrons habituals.

> [card] [Estats](https://docs.didit.me/ca/business-verification/statuses.md)
>
> Referència dels estats de sessió i de funcionalitat.

> [card] [Esquema de resposta](https://docs.didit.me/ca/business-verification/response-schema.md)
>
> Com interpretar el payload de la decisió KYB.


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