Eventos

Os sete eventos da jornada: quando cada um dispara e o que carrega.

Sete eventos, na ordem da jornada. Você escolhe quais receber ao cadastrar o endpoint.

Evento	Dispara quando	Corpo extra
verification.created	o seu backend criou a verificação	não
verification.started	a pessoa abriu o link e começou	não
verification.document_submitted	a pessoa enviou uma imagem de documento	não
verification.document_processed	a análise do documento terminou	não
verification.liveness_settled	a prova de vida chegou a um desfecho	não
verification.decided	a verificação chegou ao desfecho final	verification
verification.scored	o score ficou pronto	score

Envelope

Todo evento chega na mesma forma. Nenhum dado da pessoa atravessa o webhook.

Corpo

{
  "id": "019f0000-0000-7000-8000-000000000001",
  "event": "verification.started",
  "occurred_at": "2026-09-14T17:30:00.000Z",
  "tenant_public_id": "019f0000-0000-7000-8000-000000000002",
  "resource": {
    "type": "verification",
    "public_id": "019f0000-0000-7000-8000-000000000000"
  }
}

Campo	O que é
id	o identificador da entrega, igual ao header X-Legitimuz-Delivery
event	o nome do evento. Nunca muda; evento novo entra por adição
occurred_at	quando o evento aconteceu, em ISO 8601 UTC
tenant_public_id	a conta dona do recurso
resource.public_id	o public_id da verificação

Campos novos podem aparecer. Não valide com schema que rejeita desconhecidos.

Eventos sem corpo extra

Chegam só com o envelope. Servem para acompanhar o progresso da jornada.

verification.created · evento

O seu backend chamou POST /public/verifications com sucesso. A pessoa ainda não abriu nada.

verification.started · evento

A pessoa abriu a verificação e a primeira etapa carregou. O status passa a started.

verification.document_submitted · evento

Uma imagem de documento foi enviada. Frente e verso disparam duas vezes. Não traz resultado: a análise é assíncrona e termina em verification.document_processed.

verification.document_processed · evento

A análise do documento terminou. Fala só do documento: a verificação ainda não foi decidida.

verification.liveness_settled · evento

A prova de vida chegou a um desfecho, aprovada ou recusada.

Eventos com corpo extra

verification.decided

O desfecho da verificação. É o único evento com o veredito no corpo, e o que a maioria das integrações escuta.

Corpo

{
  "id": "019f0000-0000-7000-8000-000000000007",
  "event": "verification.decided",
  "occurred_at": "2026-09-14T17:30:00.000Z",
  "tenant_public_id": "019f0000-0000-7000-8000-000000000002",
  "resource": { "type": "verification", "public_id": "019f0000-0000-7000-8000-000000000000" },
  "verification": {
    "status": "approved",
    "ref_id": "pedido-4471",
    "decided_at": "2026-09-14T17:29:58.000Z"
  }
}

Campo	O que é
verification.status	approved, reproved ou review
verification.ref_id	a chave que você mandou na criação. null se não mandou
verification.decided_at	quando o desfecho aconteceu

review não é recusa. Quando um analista decide no dashboard, este evento dispara de novo com o status final. O seu handler precisa aceitar verification.decided duas vezes para a mesma verificação.

verification.scored

Os dois scores da verificação. Independente de verification.decided: não assuma ordem entre os dois.

{
  "id": "019f0000-0000-7000-8000-000000000008",
  "event": "verification.scored",
  "occurred_at": "2026-09-14T17:31:04.000Z",
  "tenant_public_id": "019f0000-0000-7000-8000-000000000002",
  "resource": { "type": "verification", "public_id": "019f0000-0000-7000-8000-000000000000" },
  "score": {
    "risk_score": 18,
    "identity_score": 94,
    "updated_at": "2026-09-14T17:31:03.000Z"
  }
}

Campo	O que é
score.risk_score	0 a 100. Quanto maior, pior
score.identity_score	0 a 100. Quanto maior, melhor
score.updated_at	quando os dois números foram calculados. ISO 8601 em UTC

O evento traz os números, não o detalhamento por regra. Para ver o que compôs cada score, abra a aba Composição de Score da verificação no dashboard.

Como ler os dois scores

O que cada eixo mede e como usá-lo sem transformá-lo na decisão.

Próximo passo

Segurança

Confira a assinatura antes de confiar em qualquer um destes corpos.