# 查询 Webhook 接入点列表

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

`GET https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints`

查询当前账号和项目中的 Webhook 接入点。接口一次返回全部匹配结果，最多 20 条，不分页。

响应不包含签名密钥。无匹配结果时返回空数组。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [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>
## 请求参数

### Query 参数

> 在 URL Query String 中传入。

**status** `string` | 状态筛选

按接入点状态筛选结果。仅支持 `ACTIVE` 和 `DISABLED`；省略时返回两种状态的全部接入点。

## 响应参数

**data** `object[]` | 接入点列表

查询到的 Webhook 接入点列表。每项包含完整配置和业务投递统计，不包含签名密钥。

**consecutive_failures** `integer` | 连续失败数

`data.consecutive_failures`

连续最终投递失败的业务事件数量。业务事件成功投递或重新启用接入点时清零；单个事件的多次尝试只计一次。

**最小值**：`0`

**created_at** `string` | 创建时间

`data.created_at`

Webhook 接入点的创建时间，采用 RFC 3339 格式。

**description** `string / null` | 接入点描述

`data.description`

Webhook 接入点的用途说明。未设置时返回 `null`。

**disabled_reason** `string / null` | 停用原因

`data.disabled_reason`

Webhook 接入点当前的停用原因。接入点处于 `ACTIVE` 状态时返回 `null`。

> **说明**
>
> 停用原因取值：
>
> * `manual`：调用方手动停用。
> * `consecutive_failures`：连续 20 个业务事件最终投递失败。
> * `redirect`：回调地址返回 3xx，平台不跟随重定向。
> * `unsafe_url`：回调地址未通过公网地址安全校验。
> * `invalid_certificate`：HTTPS 证书或主机名校验失败。

**events** `string[]` | 订阅事件

`data.events`

该接入点订阅的业务事件类型列表。平台仅向该接入点投递列表中的事件。可选值：`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`。

**id** `string` | 接入点 ID

`data.id`

Webhook 接入点 ID，以 `wep-` 开头。后续管理操作通过该 ID 定位接入点。

**last_error_code** `string / null` | 最近失败分类

`data.last_error_code`

最近一次业务事件最终投递失败的错误分类。尚无最终失败时返回 `null`；测试事件不更新该字段。

> **说明**
>
> 失败分类包括：
>
> * `redirect`：回调地址返回 3xx。
> * `unsafe_url`：回调地址未通过公网地址安全校验。
> * `invalid_certificate`：HTTPS 证书或主机名校验失败。
> * `http_rejected`：收到不重试的 HTTP 4xx。
> * `http_retryable`：收到可重试的 HTTP 状态码，且全部尝试均失败。
> * `network_error`：网络错误，且全部尝试均失败。

**last_failure_at** `string / null` | 最近失败时间

`data.last_failure_at`

最近一次业务事件最终投递失败的时间。尚无最终失败时返回 `null`；测试事件不更新该字段。

**last_http_status** `integer / null` | 最近失败状态码

`data.last_http_status`

最近一次业务事件最终投递失败时收到的 HTTP 状态码。因网络错误未收到响应或尚无最终失败时返回 `null`；测试事件不更新该字段。

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

**last_success_at** `string / null` | 最近成功时间

`data.last_success_at`

最近一次业务事件成功投递的时间。尚无成功投递时返回 `null`；测试事件不更新该字段。

**status** `string` | 接入点状态

`data.status`

Webhook 接入点的启用状态。`ACTIVE` 表示接收业务事件；`DISABLED` 表示暂停业务事件投递。

**updated_at** `string` | 更新时间

`data.updated_at`

Webhook 接入点配置、签名密钥或启停状态最后一次变化的时间，采用 RFC 3339 格式。业务投递统计变化不会更新该字段；自动停用会更新该字段。

**url** `string` | 回调地址

`data.url`

平台发送 Webhook 请求的公网 HTTP 或 HTTPS 地址。平台不跟随重定向。


## 代码示例

## 查询 Webhook 接入点列表

### cURL


#### Request

```bash
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints" \
  -H "Authorization: Bearer $ARK_API_KEY"
```

#### Response

```
HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "wep-20261012080000-a1b2c",
      "url": "https://example.com/webhooks/managed-agents",
      "description": "接收 Session 空闲和终止通知",
      "events": [
        "session.status_idled",
        "session.status_terminated"
      ],
      "status": "ACTIVE",
      "created_at": "2026-10-12T08:00:00Z",
      "updated_at": "2026-10-12T08:00:00Z",
      "disabled_reason": null,
      "consecutive_failures": 0,
      "last_success_at": null,
      "last_failure_at": null,
      "last_error_code": null,
      "last_http_status": null
    }
  ]
}
```