API de webhooks KYB: eventos, payloads e assinatura

Os webhooks de KYB da Didit avisam o seu backend quando uma sessão de verificação de empresas muda de status ou quando um revisor ou o registro de empresas altera os dados dela. As entidades empresariais têm seus próprios eventos. Assine os eventos que interessam a você pela API de destinos de webhook ou pelo Business Console.

Catálogo de eventos

Os eventos de sessão são compartilhados entre sessões de usuário e de empresa. O campo session_kind no payload indica a que tipo de sessão o evento se refere. Os eventos de entidade são separados dos eventos de sessão.

Eventos de sessão

Evento	Quando é disparado
`status.updated`	O status de uma sessão mudou. Em sessões de Verificação de empresas (KYB), o payload traz `session_kind: "business"`. É este o evento a acompanhar para saber o andamento.
`data.updated`	Um revisor editou os dados do registro de empresas, pulou ou gerou novamente as pessoas-chave no console, ou o registro de empresas informou uma alteração (quando o monitoramento do registro de empresas está disponível). O campo `trigger` indica qual foi o caso.

data.updated não é enviado quando o solicitante faz upload de um documento ou envia as pessoas-chave, nem quando uma nova varredura AML termina. Use status.updated ou consulte a decisão da sessão para acompanhar esse andamento.

Eventos da entidade de empresa

Evento	Quando é disparado
`business.status.updated`	O status da entidade de empresa vinculada mudou (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	Os campos de perfil ou os contadores agregados da entidade de empresa mudaram.

Assine qualquer combinação de eventos no seu destino de webhook. Consulte webhooks de entidade para a referência completa dos eventos das entidades de empresa e de usuário.

Formato do payload

Os webhooks de sessão usam um payload plano, sem um invólucro data. O envelope, os cabeçalhos de assinatura e todos os campos compartilhados estão documentados na referência de webhooks. Uma sessão de KYB adiciona estes campos:

Campo	Tipo	Descrição
`session_kind`	`"business"`	Permite que um handler genérico diferencie KYC de KYB.
`business_session_id`	`uuid`	Igual a `session_id`.
`vendor_business_id`	string	O seu identificador da entidade empresarial, quando informado na criação da sessão.
`status`	string	O rótulo exato, por exemplo `"In Progress"`, `"Approved"` ou `"Awaiting User"`. Consulte os status.
`trigger`	string	Opcional. O motivo do disparo do webhook. Em `data.updated` para KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` ou `"kyb_registry_change"`.
`decision`	object	Presente quando `status` é `Approved`, `Declined`, `In Review` ou `Abandoned`. Tem o mesmo formato de `GET /v3/session/{id}/decision/`; consulte o esquema de resposta.
`resubmit_info`	object	Presente quando `status` é `Resubmitted`.

`status.updated` para uma sessão de 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" }
}

O bloco decision traz registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] e os demais arrays de KYB.

`data.updated` para uma sessão de KYB

data.updated traz o mesmo envelope plano de status.updated, mais um trigger que indica o motivo do disparo. Quando o status da sessão é Approved, Declined, In Review ou Abandoned, ele também traz a decision atual. Busque a decision novamente para ver o que mudou. O payload não tem uma lista changed_fields.

`business.status.updated` e `business.data.updated`

Os eventos de entidade também são planos. Eles trazem vendor_business_id, vendor_data, status (ACTIVE, FLAGGED ou BLOCKED) e created_at. business.status.updated adiciona previous_status. business.data.updated adiciona changed_fields e um mapa changes no formato { 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"
}

Verificação de assinatura

Todo webhook é assinado com HMAC-SHA256 usando o segredo compartilhado do seu destino. Verifique o corpo bruto da requisição com o cabeçalho X-Signature-V2 (recomendado) e rejeite as entregas cujo X-Timestamp tenha mais de 300 segundos. A referência de webhooks lista todos os cabeçalhos de assinatura, o período de sobreposição na rotação do segredo de assinatura e exemplos de código.

Política de novas tentativas

Uma resposta 5xx ou 404, um timeout ou uma falha de conexão gera até 2 novas tentativas, após cerca de 1 minuto e cerca de 4 minutos, e depois a entrega é descartada.
Outras respostas 4xx e 3xx não geram novas tentativas.
Cada nova tentativa mantém o mesmo event_id, então faça a deduplicação com base nele.
Você pode reenviar uma entrega pelo log de entregas do destino. A referência de webhooks traz a política completa.

Como assinar

Assine os eventos que interessam a você em um 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"
    ]
  }'

Filtre as sessões de empresa do seu lado verificando session_kind === "business" dentro dos eventos status.updated e data.updated.

Próximos passos

Referência de webhooks

Destinos, assinatura, novas tentativas e padrões comuns.

Status

Referência de status de sessões e recursos.

Esquema de resposta

Como interpretar o payload da decisão de KYB.

Primeiros passos

Recursos

Perfis de empresas

Referência

Console

API de webhooks KYB: eventos, payloads e assinatura

Catálogo de eventos

Eventos de sessão

Eventos da entidade de empresa

Formato do payload

`status.updated` para uma sessão de KYB

`data.updated` para uma sessão de KYB

`business.status.updated` e `business.data.updated`

Verificação de assinatura

Política de novas tentativas

Como assinar

Próximos passos

Referência de webhooks

Status

Esquema de resposta

​Catálogo de eventos

​Eventos de sessão

​Eventos da entidade de empresa

​Formato do payload

​status.updated para uma sessão de KYB

​data.updated para uma sessão de KYB

​business.status.updated e business.data.updated

​Verificação de assinatura

​Política de novas tentativas

​Como assinar

​Próximos passos

Referência de webhooks

Status

Esquema de resposta

Catálogo de eventos

Eventos de sessão

Eventos da entidade de empresa

Formato do payload

`status.updated` para uma sessão de KYB

`data.updated` para uma sessão de KYB

`business.status.updated` e `business.data.updated`

Verificação de assinatura

Política de novas tentativas

Como assinar

Próximos passos