Webhook

Webhook 让 AI Studio 主动向外部 HTTP 接收端推送数据或事件，调用方不必持续轮询。仓库当前确认了两类用途：

• 数据导出： 将 Catalog 中的处理结果推送到外部系统；

• 平台通知： 将产品当前开放的作业、告警等事件发送到通知渠道或自定义接收端。

Webhook 与 REST 数据源方向相反：REST 数据源从第三方接口读取数据并写入 Catalog，Webhook 则由 AI Studio 向外发送。

先取得实际契约

不同导出任务、事件类型和部署版本可能使用不同负载。配置接收端之前，从相应配置页确认：

信息	用途
HTTP 方法和目标 URL 要求	配置路由
请求头和内容类型	读取正文、识别版本
负载示例与字段说明	实现解析和校验
签名、密钥或来源限制	验证请求来源
成功响应条件	确定何时确认接收
超时、重试和重放规则	设计幂等与容量

本仓库尚未提供所有 Webhook 共用的固定事件封装、签名算法或重试次数。不要假定负载一定包含 id、event、timestamp 等字段，也不要从其他产品的 Webhook 示例推断签名规则。

配置流程

1. 在接收系统创建专用 HTTPS 路由，并限制其只处理预期方法和内容类型。

2. 在 AI Studio 的导出、通知或告警配置中选择页面提供的 Webhook 方式。

3. 填写接收 URL 以及页面要求的凭证或密钥。

4. 保存后使用页面提供的测试功能；若没有测试功能，从低风险任务触发一条事件。

5. 对照实际请求确认请求头、原始正文、响应和重复投递行为。

6. 验证通过后再启用生产事件，并添加失败率和处理积压监控。

通知页面实际提供的事件类型、渠道和规则取决于当前部署。没有显示的事件不应视为已经支持。

接收端处理顺序

推荐按以下顺序处理请求；这是接收端设计建议，不是对平台负载字段的承诺：

读取原始请求体
  → 按配置页规定的方法验证来源或签名
  → 检查内容类型、大小和必要字段
  → 使用事件标识或业务键去重（仅当负载提供）
  → 将任务持久化到队列或数据库
  → 按平台规定返回成功响应
  → 异步执行耗时的业务处理

签名通常需要原始字节，因此不要在验证之前重新序列化 JSON。若平台没有提供签名能力，可结合 HTTPS、独立的高熵 URL、网关鉴权、IP 允许列表或网络隔离；采用哪种方式取决于当前部署和组织安全策略。

幂等与重试

只有实际配置说明才能确定平台何时重试。接收端仍应假设同一业务消息可能多次到达：

• 如果负载提供稳定的事件标识，以该标识建立唯一约束；

• 如果没有事件标识，选择不会把不同事件合并的业务键，并设置合适的去重时间窗；

• 将“已接收”和“业务处理完成”分开记录；

• 业务处理失败时由接收端队列重试，不要依赖平台一定再次投递；

• 记录投递时间、事件类型（如有）、处理状态和关联请求标识，避免记录秘密或完整敏感正文。

是否应在持久化后立即返回 2xx，取决于平台定义的成功响应和业务一致性要求。接收端处理时间必须低于配置页标明的超时。

演练接收端

可以先向自己的测试路由发送一个自定义请求，验证路由、日志和响应；该请求只测试接收端，不模拟 AI Studio 的正式负载：

curl --request POST "$WEBHOOK_TEST_URL" \
  --header "Content-Type: application/json" \
  --data '{"source":"local-test"}'

随后必须使用 AI Studio 的测试功能或真实低风险事件再次验证。正式解析器只应接受配置页声明并在实际请求中观察到的结构。

变更与密钥轮换

修改 URL、负载版本或签名密钥时，尽量让新旧配置短暂并存：

1. 部署能识别新契约的接收端；

2. 在测试环境切换配置并验证；

3. 切换生产投递；

4. 确认旧地址没有新流量后再撤销旧密钥和路由。

如果页面没有提供双密钥或版本协商，不要假定能够无中断轮换，应安排维护窗口或通过网关完成过渡。

排查

现象	检查项
从未收到请求	事件或任务是否真正触发、URL 是否可从平台访问、DNS 与防火墙
反复投递	返回状态是否符合成功条件、处理时间是否超过超时、接收端是否在响应前失败
验签失败	是否使用原始正文、密钥是否对应当前配置、时间与编码处理是否符合实际算法
解析失败	内容类型、事件类型、负载版本和可选字段处理
测试成功但生产失败	生产事件大小、并发、权限和下游依赖

数据导出与能力边界见平台开放能力，通知渠道配置见告警与通知。

最后更新于 2026 年 8 月 8 日