跳转到主要内容
POST
/
api
/
v1
/
agents
/
{agentId}
/
tasks
/
{taskId}
/
webhooks
注册任务终止事件的 webhook 回调。
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/agents/{agentId}/tasks/{taskId}/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "token": "<string>",
  "secret": "<string>"
}
'
{
  "success": true,
  "data": {
    "webhook_id": "<string>",
    "task_id": "<string>",
    "url": "<string>",
    "has_secret": true,
    "created_at": "2023-11-07T05:31:56Z"
  }
}

授权

​
Authorization
string
header
必填

通过 Authorization: Bearer <token> header 传用户 JWT 或 oag_ User API Key。两者都由 openapi-gateway 对 Auth service 验证。

JWT 与 API Key 都是 user-scoped：每个 key（以及每个 JWT） 绑定到唯一 owner，所有路由都自动放开该 owner 名下的全部资源。 跨租户访问由 handler 内的 owner-ACL 拦截 —— API 表面没有 per-route scope 词汇。

v1.1.0 已移除： 历史 scope 词汇（agents:* / tasks:* / files:* / instances:*）以及 403 insufficient_scope 错误码已下线。已签发的 oag_ key 自动获得 owner 全权限， 无需重建。之前显式传 scopes 调用 createAPIKey 的 SDK 客户端可以直接删除该参数。详见文末 changelog 迁移说明。

路径参数

​
agentId
string
必填
Maximum string length: 128
​
taskId
string
必填
Maximum string length: 128

请求体

application/json
​
url
string<uri>
必填

POST 回调到的绝对 HTTPS 端点。接收方拿到协议特定 payload （OpenAPI：task event 信封；A2A：JSON-RPC StreamResponse； MCP：notification）。

​
token
string

可选 bearer token，每次回调上作为 Authorization: Bearer <token> 发，接收方据此验证调用。

​
secret
string

P2-A —— HMAC-SHA256 签名 key。设了时投递器签名每次回调 body、发 X-BeeOS-Signature: t=<unix>,v1=<hex>，其中 hex = hmac_sha256(secret, t || "." || body)。接收方 应重跑同样 HMAC 鉴证；时间戳不匹配（推荐 ±5 分钟容忍） 应拒绝以防回放。

只写。Get / List 响应从不 echo；TaskWebhookResponse 上的 has_secret 布尔是唯一可观察信号。轮转方式：Set 新值；update 时传 "" 保留已有 secret（清除请 DELETE + 重注册）。

Required string length: 16 - 256

响应

Webhook 已注册。

​
success
boolean
必填
​
data
object
必填