Skip to main content

Visão Geral

Quando uma verificação KYC termina, a Campeão Sec faz um POST para a URL que você configurou. O webhook é a forma recomendada de saber o resultado — mais confiável do que polling e mais completo do que o onSuccess do widget.

Configurar URL

Você pode definir a URL de webhook de duas formas: 1. No portal — em app.campeaosec.com → Webhooks, configure uma URL padrão para o ambiente sandbox e outra para produção. 2. Por sessão — envie webhook_url ao criar a sessão para sobrescrever a URL padrão:

Eventos


Payload

verification.completed (aprovado ou reprovado)

verification.manual_review

Campos

O número do documento é sempre mascarado no payload (apenas os 3 últimos dígitos visíveis) para conformidade com a LGPD.

Validar Assinatura

Cada request inclui o header X-Campeao-Signature com uma assinatura HMAC-SHA256 do payload. Sempre valide a assinatura antes de processar o evento.
O segredo para validação fica em app.campeaosec.com → Webhooks → Secret.

Exemplos de Validação


Retry Automático

Se seu servidor não responder 200 OK em até 10 segundos, a entrega é reagendada automaticamente: Após 5 tentativas sem sucesso, a verificação muda para status: "webhook_failed". Nesse caso, use o fallback abaixo.

Fallback: Consultar Resultado Diretamente

Se o webhook não chegar (por problemas de rede, servidor offline etc.), consulte o resultado via API:
O verification_id está disponível no onSuccess do widget (result.verification_id).

Boas Práticas

  • Responda 200 OK rapidamente — processe o evento de forma assíncrona (fila, background job) e retorne 200 imediatamente
  • Seja idempotente — o mesmo evento pode ser entregue mais de uma vez; use verification_id como chave de deduplicação
  • Sempre valide a assinatura — nunca processe eventos sem confirmar o HMAC
  • Use o raw body para validação — parse o JSON somente após validar a assinatura no payload original