---
url: /reference/events.md
---
# 事件（回调）

回调事件：补拉与重发

漏收回调时用。事件类型：deposit.confirmed；withdraw.broadcasted / confirmed / failed / rejected

## 事件列表

```http
GET /v1/events
```

API key 权限范围: `read`

事件列表：按事件倒序，游标分页；可按投递状态找出没送达的（如 FAILED）

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `type` | 查询 | string | 否 | 事件类型：可选 |
| `delivery_status` | 查询 | string | 否 | 投递状态：可选 |
| `start_time` | 查询 | string | 否 | 开始时间：按事件时间，Unix 毫秒，含 |
| `end_time` | 查询 | string | 否 | 结束时间：按事件时间，Unix 毫秒，含 |
| `page_size` | 查询 | integer | 否 | 每页条数：默认 20，最大 100（超过按 100） |
| `page_token` | 查询 | string | 否 | 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 |

**响应** (200, `EventPage`)

| 字段 | 类型 | 说明 |
|---|---|---|
| `events` | object (Event)\[] |  |
| `events[].created_at` | string | 事件时间（Unix 毫秒） |
| `events[].data` | object | 事件数据：与对应 GET 接口返回的资源完全一致（deposit.confirmed → GET /v1/deposits/{deposit_id}），为事件发生时的快照 |
| `events[].delivery_status` | string | 投递状态：PENDING（待投递）/ RETRY（失败等待重试）/ SUCCESS（商户已返回 2xx）/ FAILED（重试用尽） |
| `events[].event_id` | string | 事件ID（回调请求头 X-Webhook-Id 与 body 里的 event_id） |
| `events[].last_http_status` | integer | 最后一次投递的 HTTP 状态码，没有为 0 |
| `events[].retry_count` | integer | 失败重试轮次（每轮最多即时重试 3 次，之后按退避等待下一轮；超过上限标记 FAILED） |
| `events[].type` | string | 事件类型：deposit.confirmed / withdraw.broadcasted / withdraw.confirmed / withdraw.failed / withdraw.rejected |
| `next_page_token` | string | 下一页的 page_token；为空表示没有更多 |

响应示例：

```json
{
  "events": [
    {
      "created_at": "1762650000000",
      "data": {},
      "delivery_status": "PENDING",
      "event_id": "evt_1987654321098754",
      "last_http_status": 0,
      "retry_count": 0,
      "type": "deposit.confirmed"
    }
  ],
  "next_page_token": ""
}
```

失败时返回统一错误体，见 [错误处理](/guide/errors)。

## 重发事件

```http
POST /v1/events/{event_id}/resend
```

API key 权限范围: `read`

重发事件：立即按商户当前的回调地址与回调密钥重新投递一次（event_id 不变，商户按它去重）

**请求参数**

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `event_id` | 路径 | string | 是 | 事件ID：evt\_ 开头 |

**请求体**

| 字段 | 类型 | 说明 |
|---|---|---|
| `event_id` | string | 事件ID：evt\_ 开头 |

请求示例：

```json
{
  "event_id": "evt_1987654321098754"
}
```

**响应** (200, `Event`)

| 字段 | 类型 | 说明 |
|---|---|---|
| `created_at` | string | 事件时间（Unix 毫秒） |
| `data` | object | 事件数据：与对应 GET 接口返回的资源完全一致（deposit.confirmed → GET /v1/deposits/{deposit_id}），为事件发生时的快照 |
| `delivery_status` | string | 投递状态：PENDING（待投递）/ RETRY（失败等待重试）/ SUCCESS（商户已返回 2xx）/ FAILED（重试用尽） |
| `event_id` | string | 事件ID（回调请求头 X-Webhook-Id 与 body 里的 event_id） |
| `last_http_status` | integer | 最后一次投递的 HTTP 状态码，没有为 0 |
| `retry_count` | integer | 失败重试轮次（每轮最多即时重试 3 次，之后按退避等待下一轮；超过上限标记 FAILED） |
| `type` | string | 事件类型：deposit.confirmed / withdraw.broadcasted / withdraw.confirmed / withdraw.failed / withdraw.rejected |

响应示例：

```json
{
  "created_at": "1762650000000",
  "data": {},
  "delivery_status": "PENDING",
  "event_id": "evt_1987654321098754",
  "last_http_status": 0,
  "retry_count": 0,
  "type": "deposit.confirmed"
}
```

失败时返回统一错误体，见 [错误处理](/guide/errors)。