Visão Geral
Quando uma verificação KYC termina, a Campeão Sec faz umPOST 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 — enviewebhook_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 headerX-Campeao-Signature com uma assinatura HMAC-SHA256 do payload. Sempre valide a assinatura antes de processar o evento.
Exemplos de Validação
Retry Automático
Se seu servidor não responder200 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:verification_id está disponível no onSuccess do widget (result.verification_id).
Boas Práticas
- Responda
200 OKrapidamente — 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_idcomo 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

