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

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 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` abaixo.
`decision`	string\|null	Decisão de negócio calculada pelo motor KYC. Ver valores de `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` 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

{
  "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=<hmac-sha256(webhook_secret, body)>

Consulte o guia de segurança de webhook 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.

Começando

Guias

Webhooks

Referência da API

Webhooks

Webhooks

Estrutura do envelope

Eventos disponíveis

`run.completed`

`run.failed`

Campos de `data`

`status`

`decision`

`checks_summary`

Exemplo de payload

Segurança

Retries

​Webhooks

​Estrutura do envelope

​Eventos disponíveis

​run.completed

​run.failed

​Campos de data

​status

​decision

​checks_summary

​Exemplo de payload

​Segurança

​Retries

Webhooks

Estrutura do envelope

Eventos disponíveis

`run.completed`

`run.failed`

Campos de `data`

`status`

`decision`

`checks_summary`

Exemplo de payload

Segurança

Retries