Cadastrar webhooks

Cadastre o endpoint que recebe a decisão da verificação e acompanhe cada entrega pelo dashboard.

Um webhook é um endpoint seu que a Legitimuz chama quando algo acontece numa verificação. Sem ele, o seu sistema só sabe do resultado se perguntar. É por aqui que a decisão chega ao seu produto.

Os endpoints ficam em Integrações → Segurança → Webhooks, dentro da integração.

Integrações → Segurança → Webhooks

Cadastrar um endpoint

1. Clique em Novo Endpoint
2. Informe a URL e escolha os eventos

   

   A URL precisa ser HTTPS e responder de fora da sua rede. Marque os eventos que você quer receber. Para começar, Verificação decidida é o único que a maioria precisa.

3. Copie o segredo antes de fechar o diálogo

   O signing_secret aparece uma vez, no diálogo que confirma a criação do endpoint. É com ele que o seu servidor confere cada entrega. Copie e guarde no cofre de segredos do seu backend antes de sair da tela.

   Não existe como ver esse segredo de novo, e não existe botão de rotação. Ele não volta na lista de endpoints, não aparece no histórico de entregas e não é recuperável pelo suporte. Perdeu? O caminho é trocar o endpoint.

4. Dispare uma entrega de teste

   O dashboard envia um corpo de exemplo do evento que você escolher. Confirme que o seu servidor responde 2xx e que a conferência da assinatura passa.

Trocar o segredo de um endpoint

Perder o segredo, ou querer trocá-lo por higiene, dá no mesmo trabalho: o endpoint não aceita um segredo novo, então você cria outro no lugar dele.

1. Crie um segundo endpoint

   Mesma URL, mesmos eventos. Copie o signing_secret novo.

2. Aceite as duas assinaturas

   Por uma janela curta, o seu servidor confere a entrega contra o segredo antigo e o novo, e aceita se qualquer um bater. Veja trocar o segredo.

3. Remova o endpoint antigo

   Depois que as entregas em voo chegarem. Aí o seu servidor volta a conferir contra um segredo só.

Escopo do endpoint

Escopo	Recebe
Integração	só os eventos das verificações daquela integração
Conta	os eventos de todas as integrações

Endpoint por integração é o padrão sensato: o ambiente de homologação não dispara no endpoint de produção, e um canal com problema não afeta o outro.

Acompanhar as entregas

Cada entrega fica registrada com o evento, o resultado e o número da tentativa, na aba Webhooks da integração e na aba Webhooks de cada verificação.

Tipo	O que é
event	disparada por algo que aconteceu numa verificação
test	disparada por você, pelo botão de teste
replay	reenvio manual de uma entrega anterior

Dali você reenvia o que falhou. A assinatura aparece redigida no histórico.

Eventos

Evento	Quando dispara
Verificação criada	o seu backend criou a verificação
Verificação iniciada	a pessoa abriu o link e começou
Documento enviado	a pessoa enviou uma imagem de documento
Documento processado	a análise do documento terminou
Prova de vida concluída	a prova de vida chegou a um desfecho
Verificação decidida	a verificação chegou ao desfecho final
Score	o score de risco e de identidade ficou pronto

Para quem vai implementar

O contrato completo do lado do código está na tab Webhooks.

Visão geral

Por que usar, como funciona e boas práticas.

Eventos

O corpo de cada um dos sete eventos.

Segurança

Conferir a assinatura em quatro linguagens.

Próximo passo

7. Fluxos

As etapas que a pessoa percorre, e o fluxo padrão da integração.