Webhooks

O kycert envia webhooks para a URL configurada na chave de API ao final de cada run de bureau e ao final de cada rodada de verificação facial.

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.

`biometric_check.completed`

Disparado quando uma rodada de verificação facial (Face Match + Passive Liveness) termina — pelo onboarding público, pelo reenvio manual de um analista no dashboard, ou pelo job assíncrono disparado por POST /customers/{id}/documents. Uma rodada dispara um único evento, com o resultado dos dois checks juntos — nunca um evento por check. Não é disparado para verificações feitas via POST /api/v1/verificacoes/facial (endpoint standalone e síncrono — o resultado já volta na própria resposta HTTP). Requer marcar biometric_check.completed em “Eventos assinados” na configuração do endpoint (/developer/webhooks) — diferente de run.completed/run.failed, que hoje são sempre entregues ao endpoint ativo independente da seleção. Campos do payload e exemplo completo na seção “Verificação facial” mais abaixo nesta página.

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"
  }
}

Verificação facial

Campos de `data` — `biometric_check.completed`

Assinado com o mesmo secret do endpoint (kycert-signature, mesmo formato HMAC-SHA256) usado para os eventos de bureau — não há segredo separado por tipo de evento.

Campo	Tipo	Descrição
`object`	`"biometric_verification"`	Identifica o tipo do objeto. Sempre `"biometric_verification"`.
`round_id`	string (UUID)	ID da rodada — os dois checks (`face_match`, `passive_liveness`) de uma mesma chamada compartilham o mesmo `round_id`.
`customer_id`	string (UUID)\|null	ID interno do cliente.
`external_id`	string\|null	Echo do `external_id` do cliente, quando enviado em `POST /customers`. `null` se não foi informado.
`results`	object	Resultado por check — chaveado por `face_match` e `passive_liveness`. Cada entrada tem `status` (`"Approved"`, `"Declined"` ou `"Error"`) e `score` (number\|null — `null` quando `status: "Error"`). Nunca inclui imagem, URL assinada de imagem ou os `warnings` brutos retornados pelo provedor.
`completed_at`	string (ISO 8601)	Momento em que a rodada terminou.

Exemplo de payload

{
  "id":       "evt_9f8e7d6c5b4a9f8e7d6c5b4a9f8e7d6c",
  "object":   "event",
  "event":    "biometric_check.completed",
  "created":  1758540000,
  "livemode": true,
  "data": {
    "object":      "biometric_verification",
    "round_id":    "772f9622-a4bd-63f6-c938-668877662222",
    "customer_id": "661e9511-f3ac-52e5-b827-557766551111",
    "external_id": "cust_abc123",
    "results": {
      "face_match":       { "status": "Approved", "score": 92.4 },
      "passive_liveness": { "status": "Declined", "score": 40.1 }
    },
    "completed_at": "2026-09-22T12:00:00.000Z"
  }
}

Segurança

Verificar a assinatura HMAC-SHA256 no header kycert-signature:

kycert-signature: t=<timestamp>,v1=<hmac-sha256("${timestamp}.${body}", webhook_secret)>

webhook_secret é usado como string crua no HMAC — não faça hex-decode antes de assinar/verificar. 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

Verificação Facial

Referência da API

Webhooks

Webhooks

Estrutura do envelope

Eventos disponíveis

`run.completed`

`run.failed`

`biometric_check.completed`

Campos de `data`

`status`

`decision`

`checks_summary`

Exemplo de payload

Verificação facial

Campos de `data` — `biometric_check.completed`

Exemplo de payload

Segurança

Retries

​Webhooks

​Estrutura do envelope

​Eventos disponíveis

​run.completed

​run.failed

​biometric_check.completed

​Campos de data

​status

​decision

​checks_summary

​Exemplo de payload

​Verificação facial

​Campos de data — biometric_check.completed

​Exemplo de payload

​Segurança

​Retries

Webhooks

Estrutura do envelope

Eventos disponíveis

`run.completed`

`run.failed`

`biometric_check.completed`

Campos de `data`

`status`

`decision`

`checks_summary`

Exemplo de payload

Verificação facial

Campos de `data` — `biometric_check.completed`

Exemplo de payload

Segurança

Retries