API de webhooks KYB: esdeveniments, payloads i signatura

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 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 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ó 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 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 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. 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.
`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/`, consulteu l’esquema de resposta.
`resubmit_info`	object	Apareix quan `status` és `Resubmitted`.

`status.updated` per a una sessió 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 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 } }.

{
  "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 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 conté la política completa.

Subscripció

Subscriviu-vos als esdeveniments que us interessen en una destinació del 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"
    ]
  }'

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

Següents passos

Referència de webhooks

Destinacions, signatura, reintents, patrons habituals.

Estats

Referència dels estats de sessió i de funcionalitat.

Esquema de resposta

Com interpretar el payload de la decisió KYB.

Primers passos

Funcionalitats

Perfils d'empresa

Referència

Consola

API de webhooks KYB: esdeveniments, payloads i signatura

Catàleg d’esdeveniments

Esdeveniments a nivell de sessió

Esdeveniments d’entitat empresarial

Estructura del payload

`status.updated` per a una sessió KYB

`data.updated` per a una sessió KYB

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

Verificació de la signatura

Política de reintents

Subscripció

Següents passos

Referència de webhooks

Estats

Esquema de resposta

​Catàleg d’esdeveniments

​Esdeveniments a nivell de sessió

​Esdeveniments d’entitat empresarial

​Estructura del payload

​status.updated per a una sessió KYB

​data.updated per a una sessió KYB

​business.status.updated i business.data.updated

​Verificació de la signatura

​Política de reintents

​Subscripció

​Següents passos

Referència de webhooks

Estats

Esquema de resposta

Catàleg d’esdeveniments

Esdeveniments a nivell de sessió

Esdeveniments d’entitat empresarial

Estructura del payload

`status.updated` per a una sessió KYB

`data.updated` per a una sessió KYB

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

Verificació de la signatura

Política de reintents

Subscripció

Següents passos