Webhooks KYB: eventos, payloads e assinatura

Os webhooks KYB da Didit informam o seu backend quando uma sessão de verificação de empresas muda de estado ou quando um revisor ou o registo altera os dados. As entidades Business têm eventos próprios. Subscreva os eventos que lhe interessam através da API de destinos de webhook ou da Business Console.

Catálogo de eventos

Os eventos de sessão são partilhados entre sessões User e Business. O campo session_kind do payload indica a que tipo de sessão o evento se refere. Os eventos ao nível da entidade são separados dos eventos ao nível da sessão.

Eventos ao nível da sessão

Evento	Quando é disparado
`status.updated`	O estado de uma sessão mudou. Nas sessões de Verificação de empresas (KYB), o payload inclui `session_kind: "business"`. Este é o evento a seguir para acompanhar o progresso.
`data.updated`	Um revisor editou os dados do registo de empresas, ignorou ou regenerou as pessoas-chave na consola, ou o registo de empresas comunicou uma alteração (quando a monitorização do registo de empresas está disponível). O campo `trigger` indica qual foi.

O data.updated não é enviado quando o requerente carrega um documento ou submete as pessoas-chave, nem quando uma nova análise AML termina. Use status.updated ou obtenha a decisão da sessão para acompanhar esse progresso.

Eventos de entidades Business

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

Subscreva qualquer combinação no seu destino de webhook. Consulte webhooks de entidades para a referência completa dos eventos das entidades Business e User.

Estrutura do payload

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

Campo	Tipo	Descrição
`session_kind`	`"business"`	Permite a um processador genérico alternar entre KYC e KYB.
`business_session_id`	`uuid`	Igual a `session_id`.
`vendor_business_id`	string	O seu identificador da entidade Business, quando fornecido na criação da sessão.
`status`	string	O rótulo exato, por exemplo `"In Progress"`, `"Approved"` ou `"Awaiting User"`. Consulte estados.
`trigger`	string	Opcional. 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`. A mesma estrutura de `GET /v3/session/{id}/decision/`, consulte o esquema de resposta.
`resubmit_info`	object	Presente quando `status` é `Resubmitted`.

`status.updated` numa sessão 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 inclui registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] e as restantes matrizes KYB.

`data.updated` numa sessão KYB

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

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

Os eventos de entidades também são planos. Incluem vendor_business_id, vendor_data, status (ACTIVE, FLAGGED ou BLOCKED) e created_at. O business.status.updated acrescenta previous_status. O business.data.updated acrescenta changed_fields e um 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"
}

Verificação da assinatura

Cada webhook é assinado com HMAC-SHA256 usando o segredo partilhado do seu destino. Verifique o corpo bruto do pedido com o cabeçalho X-Signature-V2 (recomendado) e rejeite as entregas cujo X-Timestamp seja anterior em mais de 300 segundos. A referência de webhooks lista todos os cabeçalhos de assinatura, a 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 ligação desencadeiam até 2 novas tentativas, após cerca de 1 minuto e cerca de 4 minutos. Depois disso, a entrega é descartada.
As outras respostas 4xx e 3xx não desencadeiam novas tentativas.
Cada nova tentativa mantém o mesmo event_id, por isso deduplique com base nele.
Pode reenviar uma entrega a partir do registo de entregas do destino. A referência de webhooks tem a política completa.

Subscrição

Subscreva os eventos que lhe interessam num 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 KYB do seu lado verificando session_kind === "business" nos eventos status.updated e data.updated.

Próximos passos

Referência de webhooks

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

Estados

Referência de estados de sessão e de funcionalidades.

Esquema de resposta

Descodificação do payload de decisão KYB.

Primeiros passos

Funcionalidades

Perfis de empresas

Referência

Consola

Webhooks KYB: eventos, payloads e assinatura

Catálogo de eventos

Eventos ao nível da sessão

Eventos de entidades Business

Estrutura do payload

`status.updated` numa sessão KYB

`data.updated` numa sessão KYB

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

Verificação da assinatura

Política de novas tentativas

Subscrição

Próximos passos

Referência de webhooks

Estados

Esquema de resposta

​Catálogo de eventos

​Eventos ao nível da sessão

​Eventos de entidades Business

​Estrutura do payload

​status.updated numa sessão KYB

​data.updated numa sessão KYB

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

​Verificação da assinatura

​Política de novas tentativas

​Subscrição

​Próximos passos

Referência de webhooks

Estados

Esquema de resposta

Catálogo de eventos

Eventos ao nível da sessão

Eventos de entidades Business

Estrutura do payload

`status.updated` numa sessão KYB

`data.updated` numa sessão KYB

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

Verificação da assinatura

Política de novas tentativas

Subscrição

Próximos passos