# 查询 Webhook 事件列表

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

`GET https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints/{endpoint_id}/events`

查询指定 Webhook 接入点在最近 7 天内关联的事件信封。列表按事件发生时间倒序排列，支持按事件 ID 或事件类型精确筛选。

事件重试不会产生重复列表项。查询结果来自投递时保存的冻结信封，不会重新读取业务资源，也不包含投递状态或逐次重试明细。

接入点停用后仍可查询。删除接入点后，在 7 天墓碑保留期内仍可查询尚未过期的关联事件。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [Base URL 及鉴权](/docs/base-url-and-authentication)。

* API Key 鉴权，请在 [API Key 管理](https://ark.volcengine.com/region:cn-beijing/apiKey) 页面，获取长效 API Key。

---

<span id="request-parameters"></span>
## 请求参数

### Path 参数

**endpoint_id** `string` `必选` | 接入点 ID

Webhook 接入点 ID，以 `wep-` 开头。该 ID 可从创建或接入点列表接口的响应中获取。

### Query 参数

> 在 URL Query String 中传入。

**event_id** `string` | 事件 ID 筛选

按 Webhook 事件 ID 精确筛选。填写以 `whe-` 开头的事件 ID；省略时不按事件 ID 筛选。

**event_type** `string` | 事件类型筛选

按事件类型精确筛选。支持 Webhook 事件结构参考中列出的业务事件和 `webhook.test` 测试事件；省略时返回全部类型。取值：`session.status_run_started` / `session.status_idled` / `session.status_terminated` / `span.outcome_evaluation_end` / `session.error` / `session.thread_status_running` / `session.thread_status_idle` / `session.thread_status_terminated` / `session.updated` / `session.deleted` / `agent.created` / `agent.updated` / `agent.deleted` / `environment.created` / `environment.updated` / `environment.deleted` / `memory_store.created` / `memory_store.deleted` / `vault.created` / `vault.deleted` / `vault_credential.created` / `vault_credential.deleted` / `vault_credential.refresh_failed` / `webhook.test`。

**limit** `integer` `默认值 20` | 每页事件数

每页返回的 Webhook 事件数量。省略时默认返回 20 条。

**取值范围**：`[1, 100]`

**page** `string` | 下一页标识

下一页标识。请将上一页响应中的 `next_page` 原样传入；省略时从第一页开始查询。

## 响应参数

**data** `object[]` | Webhook 事件列表

该接入点在保留期内关联的 Webhook 事件列表，按事件发生时间倒序排列。每项是投递时保存的完整事件信封；无匹配结果时返回空数组。

**created_at** `string` | 发生时间

`data.created_at`

事件发生时间，采用 RFC 3339 格式。

**data** `object` | 事件数据

`data.data`

事件类型、资源 ID 和该事件需要的关联上下文。各事件的字段语义请参见 [Webhook 事件结构参考](/docs/webhook-events-reference)。

**id** `string` | 资源 ID

`data.data.id`

触发事件的资源 ID。线程事件返回所属 Session ID；测试事件返回被测试的接入点 ID。

**type** `string` | 事件类型

`data.data.type`

Webhook 事件类型。支持的取值和触发条件请参见 [Webhook 事件结构参考](/docs/webhook-events-reference)。

**session_thread_id** `string` | 线程 ID

`data.data.session_thread_id`

发生状态变化的 Session 线程 ID。仅线程状态事件返回该字段。

**vault_id** `string` | Vault ID

`data.data.vault_id`

凭证所属的 Vault ID。仅 Vault 凭证事件返回该字段。

**id** `string` | 事件 ID

`data.id`

Webhook 事件 ID，以 `whe-` 开头。该值与回调请求的 `webhook-id` 请求头一致。

**type** `string` | 对象类型

`data.type`

对象类型，固定为 `event`。

**next_page** `string / null` | 下一页标识

下一页标识。还有更多事件时返回字符串；已到最后一页时返回 `null`。


## 代码示例

## 查询 Webhook 事件列表

### cURL


#### Request

```bash
#!/usr/bin/env bash
curl -sS --fail-with-body \
  "https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints/$WEBHOOK_ENDPOINT_ID/events?limit=20&event_type=session.status_idled" \
  -H "Authorization: Bearer $ARK_API_KEY"
```

#### Response

```
HTTP/1.1 200 OK

{
  "data": [
    {
      "type": "event",
      "id": "whe-20261012080500-f6g7h",
      "created_at": "2026-10-12T08:05:00Z",
      "data": {
        "type": "session.status_idled",
        "id": "sesn-20261012080000-k1l2m"
      }
    }
  ],
  "next_page": null
}
```