Webhook 概述与回调投递 - 阿里云百炼 Agent Studio

Webhook 是 Workspace 级独立资源，与会话、智能体、环境平级。创建 endpoint 并订阅具名事件后，平台在事件发生时向配置的回调地址投递通知。管理接口见创建 Webhook 等页面。

投递行为

特性	说明
事件内容	仅含事件类型、资源标识和必要上下文；通过 `data.id` 查询资源最新状态
订阅范围	仅投递事件发生时已订阅的具名事件；新增订阅不补发历史事件
不保证顺序	事件可能乱序到达；排序用 `created_at`，最终状态以资源查询结果为准
可能重复	同一事件可能多次投递，始终使用相同的 `event.id`；按该标识幂等去重
失败重试	408、425、429、5xx 和网络错误最多重试 3 次，间隔 10 秒、30 秒、1 分钟；仅 2xx 视为成功，3xx 不跟随重定向
自动禁用	默认连续 20 个业务事件最终失败后自动禁用；3xx、地址安全校验失败或 HTTPS 校验失败会立即禁用
查询期限	投递事件保留 7 天，超过后无法查询
数量上限	每个 Workspace 最多创建 20 个 Webhook

Signing Secret 仅在创建和重置成功响应中返回，后续查询不再返回。Webhook 资源主键统一为 id（wep_ 前缀）；webhook_id 仅用于路径参数和查询条件。

支持的事件

events 支持以下 32 个具名事件，不支持 * 或其他通配订阅。

分类	事件
Session 管控面	`session.created`、`session.updated`、`session.archived`、`session.deleted`
Session 运行状态	`session.status_run_started`、`session.status_idled`、`session.status_terminated`
Session Thread	`session.thread_created`、`session.thread_run_started`、`session.thread_idled`、`session.thread_terminated`
Agent	`agent.created`、`agent.updated`、`agent.archived`
Deployment	`deployment.created`、`deployment.updated`、`deployment.archived`、`deployment.paused`、`deployment.unpaused`
Deployment Run	`deployment_run.started`、`deployment_run.failed`、`deployment_run.succeeded`
Environment	`environment.created`、`environment.updated`、`environment.archived`、`environment.deleted`
Vault	`vault.created`、`vault.archived`、`vault.deleted`
Vault Credential	`vault_credential.created`、`vault_credential.archived`、`vault_credential.deleted`

回调请求

平台向通过安全校验的 HTTP 或 HTTPS 地址发起 POST 请求，不跟随重定向。直接填写的公网 IP 可以投递；私网、回环、链路本地和保留地址禁止连接。每次投递都会重新生成 webhook-timestamp，并使用当前 Signing Secret 计算签名。重试时事件正文、外层 id 和 created_at 保持不变。

请求头

POST /managedagent/webhooks HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Bailian-ManagedAgent-Webhook/1.0
webhook-id: whe_01JXX8JY9BBM4BK4C2P7K3M3ZR
webhook-timestamp: 1785810621
webhook-signature: v1,BASE64_HMAC_SHA256

请求体

普通事件：

{
  "type": "event",
  "id": "whe_01JXX8JY9BBM4BK4C2P7K3M3ZR",
  "created_at": "2026-08-06T10:30:21.123Z",
  "data": {
    "id": "sesn_xxx",
    "type": "session.status_idled",
    "workspace_id": "ws_xxx"
  }
}

Thread 事件额外携带 session_thread_id，data.id 为 Session 标识，data.session_thread_id 为具体 Thread 标识。session.thread_created、session.thread_run_started、session.thread_idled 和 session.thread_terminated 都使用该结构：

{
  "type": "event",
  "id": "whe_01JXX8JY9BBM4BK4C2P7K3M3ZR",
  "created_at": "2026-08-06T10:30:21.123Z",
  "data": {
    "id": "sesn_xxx",
    "type": "session.thread_idled",
    "workspace_id": "ws_xxx",
    "session_thread_id": "sthread_xxx"
  }
}

Vault Credential 事件在 data 中额外携带 vault_id。事件正文不携带资源完整内容，接收方根据 data.id 调用对应 GET 接口查询最新资源。

验签

签名原文和算法：

signed_content = webhook-id + "." + webhook-timestamp + "." + raw_body
secret_bytes = Base64Decode(RemovePrefix(signing_secret, "whsec_"))
signature = Base64(HMAC-SHA256(secret_bytes, UTF8(signed_content)))

webhook-id 的值是外层 event.id，不是 Webhook 配置的 webhook_id。
signing_secret 为 whsec_ 加标准 Base64 文本。验签时去掉 whsec_ 前缀，再用标准 Base64 解码剩余内容，不能将完整 whsec_... 字符串直接作为 HMAC 密钥。
先读取未经修改的原始请求体完成验签，再进行 JSON 反序列化。
校验时间戳与当前时间相差不超过 5 分钟，并使用恒定时间比较验证签名。
按外层 id 幂等去重；同一事件的重复投递使用相同 id。
需要排序时使用 created_at，不能依赖接收顺序推导资源最终状态。

import base64
import hashlib
import hmac
import os
import time

secret = os.environ["AGENT_WEBHOOK_SECRET"]
secret_bytes = base64.b64decode(secret[len("whsec_"):])

def verify_webhook(raw_body: bytes, webhook_id: str, timestamp: str, signature_header: str) -> bool:
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False

        version, signature = signature_header.split(",", 1)
        if version != "v1":
            return False

        signed_payload = f"{webhook_id}.{timestamp}.".encode() + raw_body
        expected = base64.b64encode(
            hmac.new(secret_bytes, signed_payload, hashlib.sha256).digest()
        ).decode()
        return hmac.compare_digest(signature, expected)
    except (TypeError, ValueError):
        return False

响应

接收端不需要返回响应体，应在 5 秒内返回状态码。

接收端响应或错误	平台行为
200～299	投递成功，不再重试
300～399	不跟随重定向，不重试，立即禁用当前 Webhook
408、425、429	当前请求失败，进入重试
400～499 其他状态	当前投递最终失败，不重试
500～599	当前请求失败，进入重试
域名解析、连接、写入或读取超时	当前请求失败，进入重试
HTTPS 证书校验或主机名校验失败	不重试，立即禁用当前 Webhook
域名解析到私网或保留地址	禁止建立连接，立即禁用当前 Webhook

业务事件首次请求失败后最多再重试 3 次，重试等待时间依次为 10 秒、30 秒、1 分钟，共最多 4 次真实网络请求。第 4 次仍失败时记录最终失败。默认连续 20 个业务事件最终失败后自动禁用 Webhook。webhook.test 仅同步请求一次，不重试，不影响连续失败计数。

​投递行为

​支持的事件

​回调请求

​请求头

​请求体

​验签

​响应

投递行为

支持的事件

回调请求

请求头

请求体

验签

响应