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

# Monitoramento de sessão

> O módulo session_monitor acompanha a sessão já logada depois da aprovação e manda alerta no mesmo webhook assinado.

## Monitoramento de sessão

O módulo `session_monitor` observa o que acontece **depois** da aprovação. Na sessão já logada do seu site, ele acompanha ações de negócio (depósito, saque, aposta), um sinal de vida a cada trinta minutos, a localização que o navegador conceder e o aparelho. Regras determinísticas rodam no nosso servidor e, quando uma fecha, você recebe um alerta no mesmo webhook assinado de sempre, com o nome da regra, a severidade e a evidência em número.

Você cria a sessão com um flow que tenha **só** este módulo e o bloco `session_monitoring`, e entrega o `id` da sessão à página logada. Quem envia os eventos é o **navegador do usuário**, com o próprio `id` da sessão como credencial, em lotes de até vinte eventos. O `id` viaja só no cabeçalho `Authorization`: o caminho leva `self`, e um caminho com o `id` da sessão recebe `403 path_credential_retired`. Confira a resposta de cada lote: a resposta é `202` com a contagem aceita, e o reenvio do mesmo `event_id` não duplica nada.

```
// 1) no seu servidor: a sessão de monitoramento
POST /v1/verification-sessions
Authorization: Bearer unifokal_live_…
{ "flow_id": "flow_...", "reference_id": "usr_1207",
  "session_monitoring": { "window_hours": 8 } }

// 2) no navegador do usuário, durante a sessão logada
POST /v1/verification-sessions/self/monitor-events
Authorization: Bearer vs_…
{ "events": [ { "event_id": "01J9ZB6Q2M5T8K3W7R4X1C0D9E",   // ULID gerado no navegador
                "action": "withdraw",
                "occurred_at": "2026-10-01T14:31:52.114Z",
                "amount_cents": 25000 } ] }
→ 202 { "accepted": 1 }
```

**A janela, o sinal de vida e os eventos são grátis: você paga só pelo achado.** É o oposto do modelo por chamada: uma sessão de catorze eventos custa zero até encontrarmos alguma coisa. Cada alerta chega no webhook com a regra e a evidência em número.

```
// session_monitor no check_details: o alerta de sessão
{ "module": "session_monitor", "passed": null, "outcome": "pending", "score": 50,
  "data": { "monitoring": {
      "kind": "session_monitor_alert",       // distingue este evento de uma verificação de onboarding
      "alert_id": "mal_01H…",                // id opaco do achado
      "rule": "impossible_travel_session",   // qual regra fechou
      "severity": "high",                    // high | medium (não existe low)
      "evidence": { "distance_km": 412.7,    // a evidência é NUMÉRICA, nunca a coordenada
                    "interval_min": 18,
                    "implied_kmh": 1375.7 },
      "window": { "started_at": "2026-08-01T12:00:00Z", "alert_at": "2026-08-01T12:18:00Z" },
      "evidence_expired": false } } }        // true depois de 180 dias da verificação
```

No resumo `checks` o módulo sai com o **nome da regra** que fechou, ou `"clean"` quando a sessão foi observada e nada fechou. As regras respondem perguntas diferentes e você aciona coisas diferentes em cada uma, então um booleano ali esconderia a informação inteira. As chaves de `evidence` mudam conforme a `rule`, e são sempre números do achado.

**Prazo da evidência e da referência.** `evidence` e `window` ficam disponíveis por 180 dias contados da verificação do alerta. Depois disso, a consulta da verificação, a reemissão e a exportação trazem o `alert_id`, a `rule` e a `severity`, com `evidence` vazia, `window` nulo e `evidence_expired: true` (antes do prazo ele vem `false`, sempre presente). No mesmo prazo a referência sai da verificação do alerta: a consulta e a exportação trazem `reference_id: null`, e a busca pela referência deixa de achar essa verificação. O `verification_id` não muda. Guarde no recebimento do webhook o que precisar guardar por mais tempo.

> [!WARNING]
>
> **O alerta nunca recusa ninguém, e isso é estrutural.** O dado vem do navegador do usuário final e é falsificável por construção, então o pior desfecho possível é `review`: não existe caminho de recusa automática neste módulo, em nenhuma severidade e com nenhuma calibração. **E este evento não substitui a verificação de onboarding**: se o seu sistema guarda "a última verificação por `reference_id`", use o `kind` para não sobrescrever o resultado do KYC com um alerta de sessão.

**O que nunca sai no payload:** a coordenada (o que viaja é distância, intervalo e velocidade implícita), o endereço de rede e o identificador do aparelho: os dois só existem no nosso banco como derivados por chave secreta, e devolvê-los serviria apenas para alguém testar palpites contra eles.

**Avisar o seu usuário é responsabilidade sua.** Você é o controlador desta coleta: informe, antes de começar, que a sessão logada é acompanhada para proteger a conta contra uso por outra pessoa, e registre a sua base legal. Se pedir a localização ao navegador, um texto que funciona no pedido de permissão: "Usamos a sua localização aproximada só para proteger a sua conta contra acesso de outra pessoa. Você pode negar, e o site continua funcionando." Negar a permissão não bloqueia o usuário e não gera alerta por si só.

**Não confunda com o `monitoring_aml`**, que reconsulta listas de compliance sobre a **pessoa** e cobra por mês. Este observa **uma sessão** no tempo e cobra por achado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.