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

# 认证事件与 Webhook 推送

> 了解 Didit 登录活动如何同步到控制台：包括用户登录摘要与时间线、欺诈视图、事件规则，以及 auth.* Webhook 事件。

> [!WARNING]
>
> Didit Authentication 是新功能。Didit 会为您的应用开启事件投递。使用户退出登录或封禁用户的规则操作尚未生效：使用这些操作的规则会记录该操作，但不会执行。

Didit Authentication 会自动将其活动数据发送至 Didit，您无需自行提交登录事件。每个事件都会记录到具有相同 `vendor_data` 的用户名下，与该用户的验证和交易记录并列显示。

请勿再将同一次登录的 `auth.login` 事件发送到 [`/v3/events/`](https://docs.didit.me/zh/transaction-monitoring/events)。这样会导致事件被重复存储，而且这些事件不会更新用户的登录摘要，也不会触发 `auth.*` Webhook。

## 发送的内容

| 登录活动 | 存储为 | Webhook |
| - | - | - |
| 注册 | `auth.signup` | `auth.signup` |
| 登录 | `auth.login` | `auth.login` |
| 登录失败 | `auth.login_failed` | `auth.login_failed` |
| 退出登录，或会话被撤销 | `auth.logout` | 无 |
| 忘记密码 | `auth.password_forgot` | `auth.password_reset_requested` |
| 重置密码 | `auth.password_reset` | `auth.password_reset_completed` |
| 密码已修改 | `security.password_changed` | 无 |
| 添加或更改验证器 | `security.mfa_changed` | `auth.mfa_changed` |
| 从新设备登录 | `security.device_changed` | `auth.new_device` |
| 账户被锁定或封禁 | `security.account_locked` | `auth.account_locked` |
| 代理访问已批准或已撤销 | `security.agent_access_approved`、`security.agent_access_revoked` | 无 |

[机器人防护](https://docs.didit.me/zh/authentication/bot-protection.md)的判定结果（`attempt_challenged`、`attempt_blocked` 等）也会存储为 `auth.*` 事件，因此会显示在时间线中。

新设备是指其设备 ID 和指纹都与该用户之前登录过的设备均不匹配的设备。

每个事件包含以下内容：

* 登录 `method`（例如 `password` 或 `passkey`），以及登录失败或账户被锁定时的 `reason`，
* 地址和设备信息：持久设备 ID、指纹、用户代理，以及客户端提供时的机器人评分，
* 会话 ID。

对于未知或未经验证的标识符所发起的登录失败，事件中没有 `vendor_data`。Didit 永远不会接收标识符本身，只会接收其带密钥的哈希值。这些尝试不会关联到任何用户，但下方的欺诈视图仍会按账户统计这些尝试。

## 查看位置

### 用户资料

每个用户都有一份登录摘要，显示在 **用户** 列表和用户资料中，并通过 [`/v3/users/`](https://docs.didit.me/zh/management-api/users/list) 以 `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`（因安全策略被锁定）或 `BLOCKED`（被您的团队封禁）。
* 对于没有登录身份的用户，`authentication` 为 `null`。
* 您可以在 **用户** 中按登录状态、登录方式（包括“无”）和 MFA 进行筛选。

### 事件与时间线

登录事件会显示在控制台的 **事件** 页面以及每个用户的 **事件** 标签页中。查看这些事件需要 `list:transactions` 或 `read:authentication` 权限。打开某个登录事件后，可以看到设备和网络信息、任何防护原因（例如 `bots`、`stuffing`、`brute`、`vpn`、`travel` 或 `attack_mode`），以及该事件所匹配的规则。

### 欺诈视图

**事件** 页面提供了现成的视图，可将登录记录与用户的其他活动结合起来分析：

| 视图 | 查找内容 |
| - | - |
| 一台设备，多个用户 | 7 天内同一设备指纹上出现 3 个或以上用户。 |
| 登录失败激增 | 同一公网 IP 在 3 个或以上账户上出现 10 次或以上登录失败（默认为 24 小时），并显示其活动最频繁的 30 分钟。 |
| 新设备，随后出款 | 来自 90 天内未出现过的设备的登录，之后 15 分钟内发生提现或转出交易。 |
| 密码已修改，随后交易 | 密码修改后 30 分钟内发生转出交易。 |
| 同一 IP 的大量会话 | 48 小时内同一 IP 为 3 个或以上用户发起 3 个或以上验证会话。 |

这些视图最多可回溯 31 天。

## 事件规则

登录事件与您的其他事件一样，会经过相同的[事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules.md)处理。**Authentication fraud** 规则包包含四个预设：

| 预设 | 匹配条件 | 操作 |
| - | - | - |
| 账户接管 | 在 3 次或以上登录失败之后，且在 1 小时内出现新设备，随后发生密码或 MFA 更改。 | 拒绝（评分 90）、标记、退出登录、封禁 |
| 凭证填充 | 在 1 小时内，来自某 IP 的登录成功，而该 IP 在 3 个或以上账户上出现 10 次或以上失败。 | 审核（评分 60）、标记、退出登录 |
| 新设备，随后出款 | 新设备登录后 15 分钟内发生提现。 | 审核（评分 60）、标记、退出登录 |
| 不可能的旅行 | 两次登录之间的距离超过 500 公里，且速度超过 1,000 公里/小时。 | 审核（评分 50）、标记、退出登录 |

在您自定义的规则中，以下字段较为实用：`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` 和 `event.ip.travel_speed_kmh`。

事件规则仅对登录事件提供两项操作：**让用户退出所有会话**和**禁止用户登录**。这两项操作尚未生效。在此之前，规则会以 `DISABLED` 状态记录这些操作，但不会执行。其他操作（评分、状态、标签、备注、名单和案件）均照常运行。

## Webhooks

将 [Webhook 目标](https://docs.didit.me/zh/integration/webhooks.md)订阅到您需要的 `auth.*` 类型。只有已订阅的目标才会收到这些事件。您可以在控制台中使用 **Try Webhook** 发送每种类型的示例。

```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"
  }
}
```

* 请使用 `auth_event.event_id` 进行去重。它是登录事件自身的 ID，同一事件的每次投递都保持不变。`auth_event.event_uuid` 可用于通过 `GET /v3/events/{event_uuid}/` 读取已存储的事件。
* 对于未指向任何已知用户的尝试，`vendor_data`、`vendor_user_id` 和 `authentication` 为 `null`。
* 请按照 Didit 所有 Webhook 的方式验证签名（参见 [webhooks](https://docs.didit.me/zh/integration/webhooks.md)）。

## 计费

认证事件不按事件计费，认证按月活跃用户计费。

## 您的应用所拥有的事件

对于发生在您自有产品中的操作，例如资料变更或提现请求，请从您的服务器（使用 `x-api-key` 调用 `POST /v3/events/`）或通过设备使用限定范围的监控 token 提交事件。参见 [事件](https://docs.didit.me/zh/transaction-monitoring/events.md) 和 [SDK 事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission.md)。请使用该用户访问令牌中的 `vendor_data`。


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