Visão geral de webhooks

Por que webhooks

Webhooks eliminam a necessidade de polling. Em vez de consultar o status repetidamente, o kycert notifica o seu servidor assim que o run é concluído. O endpoint recebe uma requisição POST com o resultado completo — você processa e responde em milissegundos.

Configuração

No dashboard kycert, vá em Integrações & API → Webhooks e cadastre a URL do seu endpoint. Alternativamente, passe webhook_url diretamente no POST /runs para sobrescrever o padrão por requisição.

Requisitos do endpoint

HTTPS obrigatório em produção (HTTP aceito apenas em sandbox)
Responder 2xx em até 30 segundos
Idempotente — o mesmo evento pode ser entregue mais de uma vez

Eventos disponíveis

Evento	Quando é disparado	`status` cobertos
`run.completed`	Run finalizado com decisão — aprovado, reprovado ou em revisão	`completed`, `blocked`, `pending_review`, `partial`
`run.failed`	Falha técnica irrecuperável — run não produziu resultado de decisão	`failed`

Runs reprovados por regra crítica chegam via run.completed com status: "blocked" e decision: "rejected". O evento run.failed indica exclusivamente falhas técnicas — nunca reprovações por regra de negócio.

Estrutura do payload

`run.completed` — aprovado

{
  "id": "evt_01J4ZR...",
  "object": "event",
  "event": "run.completed",
  "created": 1718200818,
  "livemode": true,
  "data": {
    "object": "run",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "decision": "approved",
    "risk_band": "baixo",
    "subject_type": "pf",
    "template_id": "661e9511-f3ac-52e5-b827-557766551111",
    "external_id": "cust_abc123",
    "metadata": { "channel": "app_mobile" },
    "checks_summary": { "total": 12, "valid": 12, "invalid": 0, "no_data": 0, "error": 0 },
    "created_at": "2026-06-12T14:00:00Z",
    "completed_at": "2026-06-12T14:00:18Z"
  }
}

`run.completed` — reprovado por regra crítica (`blocked`)

{
  "id": "evt_9a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d",
  "object": "event",
  "event": "run.completed",
  "created": 1781477806,
  "livemode": true,
  "data": {
    "object": "run",
    "id": "9ad7a680-0232-4da5-a3c5-934d65a87b1a",
    "status": "blocked",
    "decision": "rejected",
    "risk_band": "alto",
    "subject_type": "pf",
    "template_id": "f716ee22-3933-407b-9bf3-d82ab391ef94",
    "external_id": null,
    "metadata": {},
    "checks_summary": {
      "total": 19,
      "valid": 0,
      "invalid": 5,
      "no_data": 0,
      "error": 14
    },
    "created_at": "2026-06-14T22:56:44.091Z",
    "completed_at": "2026-06-14T22:56:44.091Z"
  }
}

`run.failed` — falha técnica irrecuperável

{
  "id": "evt_7c3f9e2a1b4d5e6f8a9b0c1d2e3f4a5b",
  "object": "event",
  "event": "run.failed",
  "created": 1781477900,
  "livemode": true,
  "data": {
    "object": "run",
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "failed",
    "decision": null,
    "risk_band": null,
    "subject_type": "pf",
    "template_id": "f716ee22-3933-407b-9bf3-d82ab391ef94",
    "external_id": null,
    "metadata": {},
    "checks_summary": { "total": 0, "valid": 0, "invalid": 0, "no_data": 0, "error": 0 },
    "created_at": "2026-06-14T23:05:00.000Z",
    "completed_at": null
  }
}

run.failed indica falha técnica irrecuperável — o run não produziu resultado de decisão. Investigue antes de reenviar. Nunca é emitido para reprovações por regra de negócio; essas chegam como run.completed com status: "blocked".

Política de retry

Se o seu endpoint retornar um status fora de 2xx ou não responder em 30 segundos, o kycert tenta novamente com backoff linear:

Tentativa	Delay acumulado
1ª (imediata)	—
2ª	+5 min
3ª	+10 min

Após 3 tentativas sem sucesso (total ~15 min), o evento é marcado como failed e nenhuma nova tentativa é realizada. O histórico de tentativas fica disponível no dashboard em Integrações & API → Webhooks → Entregas.

Retorne sempre 200 — mesmo se o processamento falhar internamente. O kycert retenta em qualquer status fora de 2xx (incluindo 4xx e 5xx). Se o seu código falhar após receber um evento válido, responda 200 e trate o erro de forma assíncrona — evitando consumir o orçamento de 3 tentativas desnecessariamente.

Deduplicação

O campo id do evento é único. Armazene os IDs processados para ignorar duplicatas em caso de retry:

// Exemplo com Redis
const wasProcessed = await redis.get(`webhook:${event.id}`)
if (wasProcessed) return // já processado
await redis.setex(`webhook:${event.id}`, 86400, '1')

// processar evento

Headers do webhook

Cada requisição de webhook inclui os seguintes headers:

Header	Descrição
`kycert-signature`	Assinatura HMAC-SHA256 no formato `t=<timestamp>,v1=<hash>`
`kycert-event-id`	ID único do evento — use para idempotência no receptor

Verificação de assinatura

Todo webhook inclui o header kycert-signature. Sempre verifique — qualquer servidor pode fazer POST para o seu endpoint. Consulte Segurança para o procedimento completo de verificação com exemplos em 3 linguagens.

Sandbox

Em sandbox, os webhooks são entregues normalmente. Use um serviço como webhook.site ou ngrok durante o desenvolvimento. O campo livemode: false identifica eventos de sandbox.

Serviços como webhook.site possuem limites de requisições no plano gratuito. Se o seu endpoint retornar 429, o kycert vai retentar — mas esgotará as 3 tentativas e marcará a entrega como failed. Em produção, use um endpoint real sem rate limit.

Começando

Guias

Webhooks

Referência da API

Visão geral de webhooks

Por que webhooks

Configuração

Requisitos do endpoint

Eventos disponíveis

Estrutura do payload

`run.completed` — aprovado

`run.completed` — reprovado por regra crítica (`blocked`)

`run.failed` — falha técnica irrecuperável

Política de retry

Deduplicação

Headers do webhook

Verificação de assinatura

Sandbox

​Por que webhooks

​Configuração

​Requisitos do endpoint

​Eventos disponíveis

​Estrutura do payload

​run.completed — aprovado

​run.completed — reprovado por regra crítica (blocked)

​run.failed — falha técnica irrecuperável

​Política de retry

​Deduplicação

​Headers do webhook

​Verificação de assinatura

​Sandbox

Por que webhooks

Configuração

Requisitos do endpoint

Eventos disponíveis

Estrutura do payload

`run.completed` — aprovado

`run.completed` — reprovado por regra crítica (`blocked`)

`run.failed` — falha técnica irrecuperável

Política de retry

Deduplicação

Headers do webhook

Verificação de assinatura

Sandbox