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

# Webhooks KYB: eventos, payloads e assinatura

> Webhooks KYB da Didit para sessões e entidades Business: acionadores, payloads e assinatura HMAC. A partir de $2.00 por verificação, sem contratos.

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](https://docs.didit.me/pt/management-api/webhook/list-destinations.md) 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](https://docs.didit.me/pt/getting-started/kyb-registry-pricing.md) 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](https://docs.didit.me/pt/sessions-api/retrieve-session.md) para acompanhar esse progresso.

### Eventos de entidades Business

| Evento | Quando é disparado |
| - | - |
| `business.status.updated` | O estado da [entidade Business](https://docs.didit.me/pt/entities/businesses/overview.md) 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](https://docs.didit.me/pt/entities/webhooks.md) 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](https://docs.didit.me/pt/integration/webhooks.md#estrutura-do-payload). 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](https://docs.didit.me/pt/business-verification/statuses.md). |
| `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/`](https://docs.didit.me/pt/sessions-api/retrieve-session), consulte o [esquema de resposta](https://docs.didit.me/pt/business-verification/response-schema.md). |
| `resubmit_info` | object | Presente quando `status` é `Resubmitted`. |

### `status.updated` numa sessão 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` 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 } }`.

```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 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](https://docs.didit.me/pt/integration/webhooks.md#verificação-da-assinatura) 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](https://docs.didit.me/pt/integration/webhooks.md#política-de-novas-tentativas) tem a política completa.

## Subscrição

Subscreva os eventos que lhe interessam num [destino de webhook](https://docs.didit.me/pt/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 KYB do seu lado verificando `session_kind === "business"` nos eventos `status.updated` e `data.updated`.

## Próximos passos

> [card] [Referência de webhooks](https://docs.didit.me/pt/integration/webhooks.md)
>
> Destinos, assinatura, novas tentativas, padrões comuns.

> [card] [Estados](https://docs.didit.me/pt/business-verification/statuses.md)
>
> Referência de estados de sessão e de funcionalidades.

> [card] [Esquema de resposta](https://docs.didit.me/pt/business-verification/response-schema.md)
>
> Descodificação do payload de decisão KYB.


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