> ## 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: eventos, payloads e assinatura > Webhooks KYB da Didit: eventos e gatilhos de sessões e empresas, payloads e assinatura HMAC. A partir de $2.00 por verificação, sem contratos. 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](https://docs.didit.me/pt-br/management-api/webhook/list-destinations.md) 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](https://docs.didit.me/pt-br/getting-started/kyb-registry-pricing.md) 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](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md) para acompanhar esse andamento. ### Eventos da entidade de empresa | Evento | Quando é disparado | | - | - | | `business.status.updated` | O status da [entidade de empresa](https://docs.didit.me/pt-br/entities/businesses/overview.md) 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](https://docs.didit.me/pt-br/entities/webhooks.md) 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](https://docs.didit.me/pt-br/integration/webhooks.md#formato-do-payload). 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](https://docs.didit.me/pt-br/business-verification/statuses.md). | | `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/`](https://docs.didit.me/pt-br/sessions-api/retrieve-session); consulte o [esquema de resposta](https://docs.didit.me/pt-br/business-verification/response-schema.md). | | `resubmit_info` | object | Presente quando `status` é `Resubmitted`. | ### `status.updated` para uma sessão de 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" } } ``` 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 } }`. ```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" } ``` ## 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](https://docs.didit.me/pt-br/integration/webhooks.md#verificação-de-assinatura) 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](https://docs.didit.me/pt-br/integration/webhooks.md#política-de-novas-tentativas) traz a política completa. ## Como assinar Assine os eventos que interessam a você em um [destino de webhook](https://docs.didit.me/pt-br/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" ] }' ``` Filtre as sessões de empresa do seu lado verificando `session_kind === "business"` dentro dos eventos `status.updated` e `data.updated`. ## Próximos passos > [card] [Referência de webhooks](https://docs.didit.me/pt-br/integration/webhooks.md) > > Destinos, assinatura, novas tentativas e padrões comuns. > [card] [Status](https://docs.didit.me/pt-br/business-verification/statuses.md) > > Referência de status de sessões e recursos. > [card] [Esquema de resposta](https://docs.didit.me/pt-br/business-verification/response-schema.md) > > Como interpretar o payload da decisão de KYB. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.