> ## Documentation Index > Fetch the complete documentation index at: https://docs.kycert.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks # Webhooks O kycert envia webhooks ao final de cada run para a URL configurada na chave de API. ## Estrutura do envelope Todo evento segue o mesmo envelope raiz: | Campo | Tipo | Descrição | | ---------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | ID único do evento no formato `evt_<32 hex>`. Use para deduplicar entregas repetidas — o kycert pode reenviar o mesmo `id` em caso de retry. | | `object` | `"event"` | Identifica o tipo do objeto raiz. Sempre `"event"`. | | `event` | string | Tipo do evento disparado. Ver [Eventos disponíveis](#eventos-disponíveis). | | `created` | number | Unix timestamp em segundos (UTC) do momento em que o evento foi gerado pelo kycert. | | `livemode` | boolean | `true` = evento de produção real. `false` = evento gerado em modo sandbox. Em produção, descarte silenciosamente eventos com `livemode: false`. | | `data` | object | Objeto com o resultado do run. Ver [Campos de `data`](#campos-de-data). | ## Eventos disponíveis ### `run.completed` Disparado quando um run finaliza — com sucesso, bloqueio por short-circuit ou pendência de revisão. Cobre os status `completed`, `blocked`, `pending_review` e `partial`. Ver [campo `status`](#status) para o significado de cada um. ### `run.failed` Disparado quando um run falha por erro técnico (`status: "failed"`) antes de completar qualquer análise significativa. `decision` será `null`. Não é esperado em operação normal — monitore e investigue se aparecer com frequência. *** ## Campos de `data` O objeto `data` contém um `run` com os seguintes campos: | Campo | Tipo | Descrição | | ---------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"run"` | Identifica o tipo do objeto. Sempre `"run"`. | | `id` | string (UUID) | ID único do bureau run. Use para buscar detalhes via `GET /api/v1/bureau/runs/{id}` ou correlacionar com eventos futuros do mesmo run. | | `status` | string | Estado final do run. Ver [valores de `status`](#status) abaixo. | | `decision` | string\|null | Decisão de negócio calculada pelo motor KYC. Ver [valores de `decision`](#decision) abaixo. | | `risk_band` | string\|null | Faixa de risco: `"baixo"`, `"medio"` ou `"alto"`. `null` quando o run não concluiu a análise de risco (ex: `status: "blocked"` por short-circuit antes da pontuação). | | `subject_type` | string | Tipo do sujeito analisado: `"pf"` (pessoa física) ou `"pj"` (pessoa jurídica). | | `template_id` | string\|null | UUID do template bureau usado na análise. `null` para runs gerados antes do sistema de templates. | | `external_id` | string\|null | Echo do `external_id` enviado no `POST /api/v1/bureau/runs`. Não é gerado nem modificado pelo kycert. Use para correlacionar o resultado com registros do seu sistema sem precisar armazenar o `run_id`. `null` se não foi enviado. | | `metadata` | object | Echo do objeto `metadata` enviado no `POST /api/v1/bureau/runs`. Não é interpretado pelo kycert — campo livre para contexto (ex: `{ "channel": "app_mobile", "agent_id": "ag_123" }`). Objeto vazio `{}` se não foi enviado. | | `checks_summary` | object | Contagem de resultados dos checks executados. Ver [campos de `checks_summary`](#checks_summary) abaixo. | | `created_at` | string (ISO 8601) | Momento em que o run foi criado. | | `completed_at` | string (ISO 8601) | Momento em que o run foi finalizado. | *** ### `status` | Valor | Evento | Significado | | ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"completed"` | `run.completed` | Run finalizou normalmente. Todas as fontes das etapas `critical` e `important` foram executadas. Consulte `decision` para o resultado. | | `"blocked"` | `run.completed` | Uma fonte crítica retornou INVALID com `on_hit: "block"` — o motor interrompeu o processamento por short-circuit. `decision` será sempre `"rejected"`. | | `"pending_review"` | `run.completed` | Run concluído, mas fontes da etapa `important` retornaram problemas. Aguarda revisão manual do analista no dashboard kycert. `decision` será `"review"`. | | `"partial"` | `run.completed` | Parte das fontes falhou por erro técnico, mas o run prosseguiu e concluiu o que foi possível. O resultado pode estar incompleto — verifique `checks_summary.error`. | | `"failed"` | `run.failed` | Run falhou por erro técnico antes de completar qualquer análise significativa. `decision` será `null`. | *** ### `decision` Decisão de negócio calculada pelo motor KYC com base nos resultados das fontes e nas regras do template. | Valor | Significado | O que fazer | | ------------ | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `"approved"` | Nenhuma fonte crítica ou importante retornou irregularidade — sujeito apto conforme as regras do template. | Prosseguir com onboarding ou operação. | | `"rejected"` | Fonte crítica retornou INVALID ou ERROR ativando short-circuit, ou risco acima do limiar configurado. | Recusar. Não reverter sem análise manual do compliance — registre o `run_id` para auditoria. | | `"review"` | Fonte importante retornou problema — aguarda decisão do analista no dashboard kycert. | Suspender a operação. Você receberá um novo evento quando o analista decidir. | | `null` | Run não concluiu a análise (`status: "failed"`) ou ainda está em processamento. | Aguardar `run.completed` ou consultar via `GET /api/v1/bureau/runs/{id}`. | *** ### `checks_summary` Contagem agregada dos resultados de todos os checks executados no run. | Campo | Tipo | Descrição | | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `total` | number | Total de checks executados no run. | | `valid` | number | Checks com resultado VALID — informação obtida, sem restrições. | | `invalid` | number | Checks com resultado INVALID — informação obtida com irregularidade ou restrição. | | `no_data` | number | Checks sem dado disponível — a fonte não retornou informação para o sujeito. Não é necessariamente negativo (ex: ausência de registros de inadimplência é neutro ou positivo). | | `error` | number | Checks que falharam por erro técnico — fonte indisponível, timeout ou resposta inesperada. Não implica restrição no sujeito. | > `valid + invalid + no_data + error = total` *** ## Exemplo de payload ```json theme={null} { "id": "evt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "object": "event", "event": "run.completed", "created": 1781458446, "livemode": true, "data": { "object": "run", "id": "62c03939-4605-4c49-8b1b-1c6e3964fd93", "status": "completed", "decision": "approved", "risk_band": "baixo", "subject_type": "pf", "template_id": "7c906a2a-dd73-45a2-a216-0ac40801828b", "external_id": "cust_abc123", "metadata": { "channel": "app_mobile" }, "checks_summary": { "total": 13, "valid": 12, "invalid": 0, "no_data": 1, "error": 0 }, "created_at": "2026-06-14T17:34:05.105Z", "completed_at": "2026-06-14T17:34:05.105Z" } } ``` *** ## Segurança Verificar a assinatura HMAC-SHA256 no header `X-Kycert-Signature`: ``` sha256= ``` Consulte o [guia de segurança de webhook](/webhooks/seguranca) para exemplos de verificação em Node.js, Python e Go. *** ## Retries O kycert tenta reenviar com backoff exponencial: +30s, +5min, +1h, +6h (5 tentativas no total). Consulte a [política completa de retry](/webhooks/overview).