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

# Eventos e webhooks de autenticação

> A atividade de login chega ao console do Didit com resumo e linha do tempo da pessoa, visões de fraude, regras de eventos e webhooks auth.*.

> [!WARNING]
>
> O Authentication é um produto novo. A Didit ativa a entrega de eventos para a sua aplicação. As ações de regra que desconectam ou bloqueiam uma pessoa ainda não estão ativas: uma regra que as usa registra a ação sem aplicá-la.

O Didit Authentication envia a própria atividade para a Didit automaticamente. Você não precisa enviar os eventos de login. Cada evento é associado à pessoa com o mesmo `vendor_data`, junto com as verificações e transações dela.

Não envie também os seus próprios eventos `auth.login` para [`/v3/events/`](https://docs.didit.me/pt-br/transaction-monitoring/events) referentes aos mesmos logins. Eles seriam armazenados duas vezes, e não atualizam o resumo de login da pessoa nem enviam webhooks `auth.*`.

## O que é enviado

| Atividade de login | Armazenado como | Webhook |
| - | - | - |
| Cadastro | `auth.signup` | `auth.signup` |
| Login | `auth.login` | `auth.login` |
| Login com falha | `auth.login_failed` | `auth.login_failed` |
| Logout ou sessão revogada | `auth.logout` | Nenhum |
| Esqueci a senha | `auth.password_forgot` | `auth.password_reset_requested` |
| Redefinição de senha | `auth.password_reset` | `auth.password_reset_completed` |
| Senha alterada | `security.password_changed` | Nenhum |
| Autenticador adicionado ou alterado | `security.mfa_changed` | `auth.mfa_changed` |
| Login a partir de um novo dispositivo | `security.device_changed` | `auth.new_device` |
| Conta travada ou bloqueada | `security.account_locked` | `auth.account_locked` |
| Acesso de agente aprovado ou revogado | `security.agent_access_approved`, `security.agent_access_revoked` | Nenhum |

As decisões da [proteção contra bots](https://docs.didit.me/pt-br/authentication/bot-protection.md) (`attempt_challenged`, `attempt_blocked` e outras) também são armazenadas como eventos `auth.*`, então aparecem na linha do tempo.

Um novo dispositivo é um dispositivo que não corresponde a nenhum ID de dispositivo nem a nenhum fingerprint a partir do qual a pessoa já fez login antes.

Cada evento contém:

* o `method` de login (por exemplo, `password` ou `passkey`) e um `reason` para falhas e bloqueios,
* o endereço IP e o contexto do dispositivo: um ID de dispositivo persistente, um fingerprint, o user agent e uma pontuação de bot, quando o cliente envia uma,
* o ID da sessão.

Um login com falha para um identificador desconhecido ou não comprovado não tem `vendor_data`. A Didit nunca recebe o identificador em si, apenas um hash dele usando uma chave. Essas tentativas nunca são vinculadas a uma pessoa, mas as visualizações de fraude abaixo ainda as contabilizam por conta.

## Onde você os vê

### O perfil da pessoa

Cada pessoa tem um resumo de login, exibido na lista e no perfil de **People** e retornado em [`/v3/users/`](https://docs.didit.me/pt-br/management-api/users/list) como `authentication`:

```json theme={null}
{
  "authentication": {
    "status": "ACTIVE",
    "methods": ["password", "passkey"],
    "mfa_enabled": true,
    "last_sign_in_at": "2026-10-14T09:12:44Z"
  }
}
```

* `status` é `ACTIVE`, `LOCKED` (bloqueado por uma política de segurança) ou `BLOCKED` (bloqueado pela sua equipe).
* `authentication` é `null` para uma pessoa sem identidade de login.
* Você pode filtrar **People** por status de login, método de login (incluindo "nenhum") e MFA.

### Eventos e linha do tempo

Os eventos de login aparecem na página **Events** do console e na aba **Events** de cada pessoa. Para lê-los, é necessária a permissão `list:transactions` ou `read:authentication`. Ao abrir um evento de login, você vê o dispositivo e a rede, qualquer motivo de proteção (por exemplo, `bots`, `stuffing`, `brute`, `vpn`, `travel` ou `attack_mode`) e as regras às quais ele correspondeu.

### Visualizações de fraude

A página **Events** tem visualizações predefinidas que combinam os logins com o restante da atividade de uma pessoa:

| Visualização | O que encontra |
| - | - |
| Um dispositivo, várias pessoas | 3 ou mais pessoas em um mesmo fingerprint de dispositivo em até 7 dias. |
| Pico de logins com falha | Um IP público com 10 ou mais logins com falha contra 3 ou mais contas (24 horas por padrão), com os seus 30 minutos de maior atividade. |
| Novo dispositivo, depois um saque | Um login a partir de um dispositivo não visto em 90 dias, seguido de um saque ou de uma transação de saída em até 15 minutos. |
| Senha alterada, depois uma transação | Uma transação de saída em até 30 minutos após uma alteração de senha. |
| Muitas sessões a partir de um IP | 3 ou mais sessões de verificação para 3 ou mais pessoas em 48 horas. |

As visualizações abrangem até 31 dias anteriores.

## Regras de eventos

Os eventos de login passam pelas mesmas [regras de eventos](https://docs.didit.me/pt-br/transaction-monitoring/event-rules.md) que os seus outros eventos. O pacote **Authentication fraud** tem quatro predefinições:

| Predefinição | Corresponde a | Ações |
| - | - | - |
| Tomada de controle de conta | Uma alteração de senha ou de MFA após 3 ou mais logins com falha e um novo dispositivo em até 1 hora. | Recusar (pontuação 90), etiquetar, desconectar, bloquear |
| Credential stuffing | Um login bem-sucedido a partir de um IP com 10 ou mais falhas em 3 ou mais contas em até 1 hora. | Revisar (pontuação 60), etiquetar, desconectar |
| Novo dispositivo, depois um saque | Um saque em até 15 minutos após um novo dispositivo. | Revisar (pontuação 60), etiquetar, desconectar |
| Viagem impossível | Mais de 500 km entre logins a mais de 1.000 km/h. | Revisar (pontuação 50), etiquetar, desconectar |

Campos úteis para as suas próprias regras incluem `event.category`, `event.action_type`, `event.payload.method`, `event.payload.reason`, `event.security.changed_field`, `event.device.fingerprint`, `event.device.persistent_device_id`, `event.device.bot_score`, `event.ip.is_vpn_or_tor`, `event.ip.is_data_center`, `event.ip.country`, `event.ip.travel_distance_km` e `event.ip.travel_speed_kmh`.

As regras de eventos têm duas ações exclusivas para eventos de login: **Sign the person out of every session** e **Block the person from signing in**. Elas ainda não estão ativas. Até que estejam, uma regra as registra com o status `DISABLED` e não as aplica. As outras ações (pontuação, status, tags, notas, listas e casos) funcionam normalmente.

## Webhooks

Inscreva um [destino do webhook](https://docs.didit.me/pt-br/integration/webhooks.md) nos tipos `auth.*` de que você precisa. Somente os destinos inscritos os recebem. Use **Try Webhook** no console para enviar um exemplo de cada tipo.

```json auth.new_device theme={null}
{
  "webhook_type": "auth.new_device",
  "event_id": "0b6f2a71-3c4d-4e5f-8a9b-0c1d2e3f4a5b",
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "timestamp": 1760433164,
  "created_at": 1760433164,
  "vendor_user_id": "8f0c3a52-4b7e-4a51-9a56-1f2d3c4b5a69",
  "vendor_data": "user-1234",
  "auth_event": {
    "event_id": "auth:3d0f1c2e-7a8b-4c5d-9e0f-1a2b3c4d5e6f",
    "event_uuid": "5b6c7d8e-9f01-4a2b-8c3d-4e5f60718293",
    "type": "security.device_changed",
    "method": "passkey",
    "reason": null,
    "occurred_at": "2026-10-14T09:12:44+00:00",
    "ip_address": "203.0.113.10",
    "device": {
      "fingerprint": "fp_7f3a",
      "label": "Chrome on Android",
      "persistent_device_id": "dev_4c21"
    }
  },
  "authentication": {
    "status": "ACTIVE",
    "methods": ["passkey"],
    "mfa_enabled": true,
    "last_sign_in_at": "2026-10-14T09:12:44Z"
  }
}
```

* Faça a deduplicação por `auth_event.event_id`, o ID próprio do evento de login: ele permanece o mesmo em todas as entregas desse evento. `auth_event.event_uuid` permite recuperar o evento armazenado em `GET /v3/events/{event_uuid}/`.
* `vendor_data`, `vendor_user_id` e `authentication` são `null` para uma tentativa que não identifica nenhuma pessoa conhecida.
* Verifique a assinatura como em qualquer webhook da Didit (consulte [webhooks](https://docs.didit.me/pt-br/integration/webhooks.md)).

## Faturamento

Os eventos de autenticação não são cobrados por evento. A autenticação é cobrada por usuário ativo por mês.

## Eventos que pertencem à sua aplicação

Para ações que acontecem no seu próprio produto, como uma alteração de perfil ou uma solicitação de saque, envie os eventos você mesmo a partir do seu servidor (`POST /v3/events/` com `x-api-key`) ou a partir do dispositivo, com um token de monitoramento com escopo restrito. Consulte [eventos](https://docs.didit.me/pt-br/transaction-monitoring/events.md) e [envio de eventos pelo SDK](https://docs.didit.me/pt-br/transaction-monitoring/sdk-event-submission.md). Use o `vendor_data` da pessoa, obtido do token de acesso dela.


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