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

O 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

Em implementação. O envelope abaixo é o contrato acordado; a entrega do bloco score ainda não está disponível em produção.

Os dois scores e o resultado de cada regra. 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",
    "breakdown": {
      "risk:proxy_or_vpn": {
        "rule_key": "risk:proxy_or_vpn",
        "rule_version": "1.0.0",
        "category": "risk",
        "title": "Proxy or VPN",
        "status": "NOT_MATCHED",
        "reason_code": "no_proxy_or_vpn_detected",
        "score_points": {},
        "evaluated_at": "2026-09-14T17:31:03.000Z",
        "details": {}
      }
    }
  }
}

Campo	O que é
score.risk_score	0 a 100. Quanto maior, pior
score.identity_score	0 a 100. Quanto maior, melhor
score.breakdown	um objeto por regra, com status, reason_code e score_points

MATCHED significa que a regra encontrou um sinal contra a jornada. INSUFFICIENT_DATA não é aprovação: a regra não teve o que avaliar. As catorze regras estão em score.

Próximo passo

Segurança

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