文档中心

火山方舟

Webhooks

创建 Webhook 接入点

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

创建 Webhook 接入点，订阅当前账号和项目中的 Managed Agents 业务事件。创建成功返回 200，接入点默认启用。

同一地域、账号和项目内最多创建 20 个接入点，启用和停用状态均计入配额。同一项目内回调 URL 必须唯一。

保存签名密钥

创建响应中的 signing_secret 仅返回一次。关闭响应前，将密钥保存在服务端的安全配置中；列表和详情接口无法再次获取。

鉴权

本接口支持鉴权方式如下，详情请参见 Base URL 及鉴权。

API Key 鉴权，请在 API Key 管理页面，获取长效 API Key。

请求参数

Body 参数

events string[] 必选 | 订阅事件

url string 必选 | 回调地址

description string / null | 接入点描述

响应参数

consecutive_failures integer | 连续失败数

created_at string | 创建时间

description string / null | 接入点描述

disabled_reason string / null | 停用原因

events string[] | 订阅事件

id string | 接入点 ID

last_error_code string / null | 最近失败分类

last_failure_at string / null | 最近失败时间

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

last_success_at string / null | 最近成功时间

signing_secret string | 签名密钥

status string | 接入点状态

updated_at string | 更新时间

url string | 回调地址

创建 Webhook 接入点

发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！

Request

curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/webhook_endpoints" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/managed-agents",
    "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:00:00Z",
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "last_error_code": null,
  "last_http_status": null,
  "signing_secret": "whsec_<BASE64_SECRET>"
}

最近更新时间：2026.10.28 11:37:20

这个页面对您有帮助吗？

有用

无用