Webhook de Verificação

Visão Geral

Este webhook é acionado quando o status de uma verificação muda para COMPLETED (Concluído) ou FAILED (Falhou). FAILED é definitivo: uma falha que ainda será repetida automaticamente fica em RETRYING e não aciona o webhook. Ele permite que você receba atualizações em tempo real sobre o status das suas solicitações de verificação.

Configuração

Ao criar uma solicitação de verificação, você pode configurar o webhook incluindo um objeto callback na sua requisição:

{
  "nationalId": "11111111111",
  "profileId": "22222222-0000-0000-0000-000000000001",
  "verifications": {
    "entity": "PERSON",
    "finance": {
      "restrictions": true
    }
  },
  "callback": {
    "url": "https://your-domain.com/webhook-endpoint",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <token>",
      "X-Tenant-Id": "my-tenant"
    }
  },
  "metadata": {
    "key": "value"
  }
}

Parâmetros de Configuração do Callback

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Sim	A URL onde o webhook será enviado. Só https, para um endereço público (ver Regras do endpoint).
method	string	Sim	Método HTTP a ser usado (POST/PUT)
headers	object (string→string)	Não	Headers HTTP adicionais enviados junto do webhook (ex: Authorization, X-Tenant-Id). Útil para autenticação no seu endpoint.

Regras do endpoint

O Zarv ID chama o seu endpoint de dentro da própria infraestrutura, então a URL do callback precisa seguir estas regras:

• Só https. http:// é recusado.
• Endereço público. O host precisa resolver só para IPs públicos. Endereços privados (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, link-local (inclusive 169.254.169.254), CGNAT, multicast e, em IPv6, tudo fora de unicast global (além de 6to4 e Teredo) são recusados. Um IP literal público é aceito.
• Sem credenciais na URL. Use headers para autenticar, nunca https://usuario:senha@....
• Certificado válido. O certificado TLS do seu endpoint é verificado (TLS 1.2 ou superior). Certificado autoassinado ou expirado faz a entrega falhar.
• Sem redirect. Um 3xx não é seguido e conta como entrega com falha. Configure a URL final.

As regras valem em toda escrita do callback: criação, lote (JSON e CSV), PUT e PATCH. Fora delas a requisição responde 400 com callback must be https to a public address. O endereço é conferido de novo no momento da entrega: um host que passou a resolver para um IP privado tem a entrega recusada.

Metadados

Você pode incluir metadados opcionais na sua requisição que serão retornados no payload do webhook. Isso é útil para rastrear referências internas ou adicionar dados personalizados às suas respostas de webhook.

Payload do Webhook

Quando o status da verificação muda, seu endpoint configurado receberá uma requisição com o method configurado (POST ou PUT), Content-Type: application/json, os seus headers e o seguinte payload:

{
  "id": "verification-id",
  "status": "COMPLETED",
  "metadata": {
    "key": "value"
  },
  "input": [{ "attribute": "renda", "value": "8000", "kind": "declared" }]
}

Campos do Payload

Campo	Tipo	Descrição
id	string	O ID da verificação retornado durante a criação
status	string	Status atual da verificação (COMPLETED ou FAILED)
failure	string	Motivo da falha. Presente só quando status é FAILED.
metadata	object	O objeto de metadados que você forneceu durante a criação da verificação (se houver)
input	array	O input enviado na criação, como foi gravado (com o kind resolvido). Ausente quando não houve input.

Considerações de Segurança

1. O endpoint do webhook precisa usar HTTPS com certificado válido (obrigatório, ver Regras do endpoint)
2. Implemente autenticação adequada no seu endpoint de webhook
3. Considere implementar lista de IPs permitidos para segurança adicional
4. Valide o payload do webhook antes do processamento

Melhores Práticas

1. Sempre responda às requisições do webhook com um código de status 200 para confirmar o recebimento
2. Implemente idempotência para lidar com entregas duplicadas de webhook
3. Processe webhooks de forma assíncrona para evitar problemas de timeout
4. Armazene os payloads dos webhooks para fins de auditoria
5. Tenha uma reconciliação por consulta (GET) para webhooks que não chegaram: depois de 3 tentativas não há reenvio

Exemplo de Implementação

Aqui está um exemplo simples de como lidar com o webhook em Node.js:

app.post("/webhook-endpoint", (req, res) => {
  const { id, status, metadata } = req.body;

  // Confirmar recebimento
  res.status(200).send("OK");

  // Processar o webhook de forma assíncrona
  processWebhook({ id, status, metadata });
});

async function processWebhook(data) {
  try {
    // Atualizar seu sistema com o status da verificação
    await updateVerificationStatus(data);

    // Registrar o webhook para fins de auditoria
    await logWebhookEvent(data);
  } catch (error) {
    // Tratar erros adequadamente
    console.error("Erro ao processar webhook:", error);
  }
}

Tratamento de Erros

Cada tentativa tem timeout de 10 segundos. A entrega é tentada até 3 vezes, num intervalo total de até 15 segundos, quando a falha pode passar numa nova tentativa:

Resposta do seu endpoint	O que acontece
2xx	Entregue.
Conexão não abriu (recusada, DNS), 5xx, 429	Nova tentativa após 1 segundo e, se falhar, após 5 segundos.
Timeout (mais de 10 segundos sem responder)	Falha, sem nova tentativa.
3xx, outros 4xx	Falha na hora, sem nova tentativa.
URL fora das regras do endpoint	Falha na hora, sem nova tentativa.

Responda rápido (veja Melhores Práticas): um endpoint que demora não recebe novas tentativas.

Se as 3 tentativas falharem, a falha é registrada do nosso lado e o webhook não é reenviado depois. Por isso, trate o webhook como um aviso e mantenha uma consulta de reconciliação: para uma verificação que não teve webhook dentro do prazo esperado, consulte GET /api/v2/verifications/{id} até COMPLETED ou FAILED.