> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos webhook de sessão biométrica

> Payloads de eventos webhook para sessões biométricas incorporadas na gu1, com eventos a nível organização e webhookUrl configurável por requisição.

## 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:

1. **Webhooks da organização** — inscreva-se em `biometric.session_*` em [configuração de webhooks](/pt/webhooks/configuration) (todas as transições de status).
2. **`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](/pt/webhooks/events/kyc-events):

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/pt/webhooks/configuration#signature-verification).

<Note>
  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.
</Note>