火山方舟
火山方舟
API参考
请输入
- 文档首页
火山方舟Managed Agents APIWebhooks更新 Webhook 接入点
复制全文
下载 pdf更新 Webhook 接入点
文档反馈
问问助手PUT https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints/{endpoint_id}
更新指定 Webhook 接入点的回调地址、描述或订阅事件。接口只更新请求中提供的字段，省略字段保持原值。
仅停用状态下可以修改回调地址。配置更新不改变接入点状态、停用原因、连续失败数或最近成功投递时间；完全相同的配置不会更新 updated_at。
鉴权
- API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。
请求参数
Path 参数
endpoint_id string 必选 | 接入点 ID
Webhook 接入点 ID，以 wep- 开头。该 ID 可从创建或列表接口的响应中获取。
Body 参数
description string / null | 接入点描述
Webhook 接入点的用途说明，最长 256 个字符。省略时保留原值；传 null 或空字符串时清空。
events string[] | 订阅事件
订阅的业务事件类型列表。提供时整体替换原列表，至少包含一个事件；省略时保留原值。
传 null 或空数组会返回 400。
移除事件类型会取消尚未开始和等待重试的对应投递。新增事件类型不会补发历史事件。取值：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。
url string | 回调地址
接收 Webhook 请求的公网 HTTP 或 HTTPS 地址。仅停用状态下可以修改，省略时保留原值。
平台不跟随重定向。
响应参数
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 接入点
发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！
Request
cURL
curl -sS --fail-with-body -X PUT \
"https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints/$WEBHOOK_ENDPOINT_ID" \
-H "Authorization: Bearer $ARK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "接收 Session 状态变更通知",
"events": [
"session.status_idled",
"session.status_terminated"
]
}'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:05:00Z",
"disabled_reason": null,
"consecutive_failures": 0,
"last_success_at": null,
"last_failure_at": null,
"last_error_code": null,
"last_http_status": null
}最近更新时间：2026.10.28 11:37:21
这个页面对您有帮助吗？
有用
有用
无用
无用