Eventos webhook de sessão biométrica

Visão geral

Sessões biométricas incorporadas são geridas de ponta a ponta pela Gu1. Quando o usuário conclui a captura na UI hospedada, a Gu1 persiste a sessão, aplica as políticas da organização (limiares de face match, cruzamento entre entidades, billing) e envia webhooks com o resultado da sessão. Sua integração deve usar payload.status como desfecho biométrico — o mesmo campo retornado por GET /api/kyc/biometric/sessions/:id. Dois canais de entrega:

Webhooks da organização — inscreva-se em biometric.session_* em configuração de webhooks (todas as transições de status).
webhookUrl por request — URL HTTPS opcional em POST /api/kyc/biometric/sessions; a Gu1 faz POST em desfechos terminais de captura (approved, rejected, abandoned, expired). Cancelamento manual via API dispara apenas webhooks da organização.

Tipos de evento

Evento	Quando
`biometric.session_created`	Sessão criada (`status: pending`)
`biometric.session_in_progress`	Usuário iniciou a captura na UI hospedada
`biometric.session_approved`	Sessão biométrica aprovada pela Gu1
`biometric.session_rejected`	Sessão biométrica rejeitada pela Gu1
`biometric.session_abandoned`	Usuário abandonou o fluxo sem concluir
`biometric.session_cancelled`	Sessão cancelada na Gu1 (apenas `pending` / `in_progress`)
`biometric.session_expired`	Sessão expirada

Sobre o payload

Mesma envoltória externa dos eventos KYC:

{
  "event": "biometric.session_approved",
  "timestamp": "2026-06-11T15:00:00Z",
  "organizationId": "org-uuid",
  "payload": { }
}

O payload interno é a linha da sessão biométrica na Gu1 (mesmo formato da API REST).

Campos do payload

payload.status — Status da sessão: pending, in_progress, approved, rejected, abandoned, cancelled, expired.
payload.rejectionCode / payload.rejectionMessage — Quando status é rejected (ex.: FACE_MATCH_SCORE_LOW, CROSS_ENTITY, CAPTURE_DECLINED).
payload.mode — face_match (liveness + comparação com retrato do KYC).
payload.sessionUrl — URL de captura enquanto a sessão está ativa.
payload.decision — Detalhe técnico da captura (scores, chaves de mídia). Imagens via GET /api/kyc/biometric/sessions/:id/media?key=.
payload.entity — Snapshot da entidade pessoa (id, externalId, name, type).

Exemplo: sessão criada

{
  "event": "biometric.session_created",
  "timestamp": "2026-06-11T14:00:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "pending",
    "mode": "face_match",
    "sessionUrl": "https://verify.example.com/session/abc",
    "hostedSessionId": "hosted-session-id",
    "rejectionCode": null,
    "rejectionMessage": null,
    "createdAt": "2026-06-11T14:00:00.000Z",
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

Exemplo: em progresso

{
  "event": "biometric.session_in_progress",
  "timestamp": "2026-06-11T14:05:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "in_progress",
    "mode": "face_match",
    "sessionUrl": "https://verify.example.com/session/abc",
    "rejectionCode": null
  }
}

Exemplo: aprovada

{
  "event": "biometric.session_approved",
  "timestamp": "2026-06-11T14:10:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "approved",
    "mode": "face_match",
    "rejectionCode": null,
    "completedAt": "2026-06-11T14:10:00.000Z",
    "decision": {
      "face_match": { "status": "Approved", "score": 99.2 },
      "liveness": { "status": "Approved", "score": 98.5 }
    },
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

Exemplo: rejeitada

{
  "event": "biometric.session_rejected",
  "timestamp": "2026-06-11T14:12:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "rejected",
    "mode": "face_match",
    "rejectionCode": "FACE_MATCH_SCORE_LOW",
    "rejectionMessage": "Face match score 28.5 is below organization threshold 30",
    "completedAt": "2026-06-11T14:12:00.000Z",
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

Códigos comuns de `rejectionCode`

Código	Significado
`FACE_MATCH_SCORE_LOW`	Score de face match abaixo do limiar (`face_match`)
`CROSS_ENTITY`	Captura corresponde a outra entidade da organização
`CAPTURE_DECLINED`	Captura recusada no fluxo hospedado

`webhookUrl` por request

Mesmos nomes de event e formato de payload dos webhooks da organização.
Assinatura HMAC em X-Webhook-Signature com o webhook secret KYC configurado.
Headers adicionais: X-Webhook-Event, X-Webhook-ID, X-Webhook-Timestamp.

Ver verificação de assinatura.

Cancelamento manual (POST /api/kyc/biometric/sessions/:id/cancel) emite biometric.session_cancelled apenas nos webhooks da organização; não faz POST ao webhookUrl do request.

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Eventos webhook de sessão biométrica

Visão geral

Tipos de evento

Sobre o payload

Campos do payload

Exemplo: sessão criada

Exemplo: em progresso

Exemplo: aprovada

Exemplo: rejeitada

Códigos comuns de `rejectionCode`

`webhookUrl` por request

​Visão geral

​Tipos de evento

​Sobre o payload

​Campos do payload

​Exemplo: sessão criada

​Exemplo: em progresso

​Exemplo: aprovada

​Exemplo: rejeitada

​Códigos comuns de rejectionCode

​webhookUrl por request

Visão geral

Tipos de evento

Sobre o payload

Campos do payload

Exemplo: sessão criada

Exemplo: em progresso

Exemplo: aprovada

Exemplo: rejeitada

Códigos comuns de `rejectionCode`

`webhookUrl` por request