# 查询 Webhook 接入点详情

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

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

查询指定 Webhook 接入点的配置、状态和业务投递统计。响应不包含签名密钥。

## 鉴权

本接口支持鉴权方式如下，详情请参见 [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 可从创建或列表接口的响应中获取。

## 响应参数

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

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

**最小值**：`0`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


## 代码示例

## 查询 Webhook 接入点详情

### cURL


#### Request

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

#### Response

```
HTTP/1.1 200 OK

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