Webhook

查看 Webhook 列表

功能说明

「Webhook 管理」页用来在当前应用下创建 Webhook，捕捉 Agent 执行过程中的关键事件。Webhook 分三类：

列表以卡片展示每个 Webhook 的类型徽标、触发时机标签、ID（可复制）、描述和创建时间，支持分页。页面提供「按 Webhook 名称搜索…」输入框，右上角有「帮我写」和「创建 Webhook」两个按钮。

前置条件

• 已进入目标应用空间。

操作步骤

1. 点击侧边栏「Webhook」进入页面。
2. 在搜索框输入名称关键字，过滤列表。
3. 点击「创建 Webhook」进入手动创建页（见手动创建 Webhook），或点击「帮我写」用 AI 生成初稿（见用「帮我写」生成 Webhook）。
4. 点击已有 Webhook 卡片，进入编辑页（见编辑与删除 Webhook）。

预期结果：没有数据时显示空状态「暂无 Webhook 数据」。

图 2-12：Webhook 管理页——右上角提供「帮我写」与「创建 Webhook」两个入口。

手动创建 Webhook

功能说明

手动创建是一个整页表单：左侧是配置区，右侧是「Webhook 调试」面板。配置区包含四个分块：基本信息、触发规则、投递配置、安全配置。

前置条件

• 已准备好可接收 POST 请求的回调地址。

操作步骤

1. 在列表页点击「创建 Webhook」，进入创建页。

2. 基本信息：填写「Hook 名称」（必填，1~128 个字符）和「描述」（可选，0~512 个字符）。

3. 触发规则：在顶部「智能体」「预算管理」两个 Tab 中选择执行时机。

   Tab	分组	执行时机
   智能体	拦截型 · 同步等待响应决策	工具调用前 / 收到用户消息时 / 定时任务执行前
   智能体	观察型 · 异步投递	工具调用后 / 会话开始时 / 智能体执行完毕 / 模型调用后 / 定时任务执行后
   预算管理	观察型 · 异步投递	预算配额通知（配额用量达到阈值时通知）

   • 「智能体」Tab 下可以多选；勾选「工具调用前」或「工具调用后」时，会出现「工具名匹配」：填 * 匹配全部工具，填单个工具名只匹配该工具，用 | 分隔多个工具名，用 /正则/ 按正则匹配。
   • 「预算配额通知」必须单独创建，不能与智能体时机组合。
   • 拦截型分组旁可点击「查看响应示例」，查看放行 Allow / 拒绝 Deny / 修改 · 工具调用前 / 修改 · 用户消息四种响应格式；观察型分组旁可点击「查看请求示例」，查看各时机投递的 JSON 请求体。

4. 投递配置：系统以 POST + Content-Type: application/json 投递事件。

   字段	说明
   回调地址	必填，完整的 HTTP 或 HTTPS 地址，路径和查询参数支持运行时变量
   超时（ms）	默认 5000；拦截型建议 ≤3000
   最大重试	仅选择观察型时出现；失败按指数退避重试
   失败策略	仅选择拦截型时出现：ALLOW「调用失败时放行」或 DENY「调用失败时拒绝」；审批、风控类场景务必选 DENY

5. 安全配置（可选，让回调请求可验证、不被冒充）：

   字段	说明
   签名密钥	可手动填写或点击「随机生成」。设置后，每次投递附带 X-Webhook-Timestamp 和 X-Webhook-Signature 请求头；点击「查看验签代码」可获取 Java / Python / Node.js / Go 验签示例
   HTTP 鉴权方式	NONE / API_KEY（Header 名称默认 X-API-Key）/ BEARER / BASIC（凭证为 Base64 编码的「用户名:密码」）/ CUSTOM（自定义请求头和查询参数）

6. （可选）在右侧「Webhook 调试」面板点击「运行调试」，验证回调链路，详见调试 Webhook。

7. 确认无误后点击右上角「创建 Webhook」；如需放弃，点击「取消」。

预期结果：表单有改动后，页面顶部出现「未保存」徽标；提交成功后返回列表，并展示新建的 Webhook。

图 2-13：Webhook 创建页——左侧为基本信息、触发规则、投递配置与安全配置，右侧为 Webhook 调试面板。

在 Webhook 中使用运行时变量

功能说明

回调地址的路径和查询参数值，以及 API Key、Bearer Token、自定义 Header 值、自定义查询参数值，都可以写运行时变量；投递时由系统替换为真实值。支持变量的输入框旁会显示「支持运行时变量（仅 path/query）」或「仅值支持运行时变量」，悬停可查看变量清单。

示例回调地址：https://example.com/hook/${sys.agentId}?uid=${ctx.userId}

注意事项 / 异常处理

• 回调地址的协议、主机和端口必须固定，不能使用变量；查询参数名、Basic 凭证、签名密钥、Header 名、Hook 名称与描述、工具名匹配同样不支持变量。
• 预算配额通知类型的 Webhook 不支持运行时变量。
• 常见校验报错：「回调地址必须是绝对 HTTP 或 HTTPS 地址」「回调地址的协议、主机和端口必须固定」「回调地址不能包含 fragment」「回调地址不能包含用户信息，且主机不能为空」「回调地址主机名格式不合法」「回调地址 Query 参数名不支持运行时变量」「…中的运行时变量语法不合法」。

调试 Webhook

功能说明

右侧「Webhook 调试」面板会向左侧配置的回调地址发送 mock 事件，不会触发任何业务逻辑。

操作步骤

1. 先在左侧完善名称、执行时机和回调地址，否则面板提示先完善配置。
2. 点击「运行调试」。如果配置中使用了运行时变量，会先弹出「填写运行时变量测试值」：系统变量已填入 DryRun 默认值，调用方变量按本次调试场景填写，然后点击「开始运行调试」。
3. 在结果区的「概览 / 请求 / 响应 / 耗时分析」四个 Tab 中查看 HTTP 状态码、响应头与响应体、耗时分解。
4. 结果不符合预期时，点击「帮我看看」生成「诊断报告」，可「复制诊断」转给回调服务的开发同学。

注意事项 / 异常处理

• 调试后修改了左侧配置，面板会提示「配置已变化」，需重新运行才能反映最新结果。
• 运行时变量的测试值只用于本次调试，关闭弹窗或离开页面后不会保留。

用「帮我写」生成 Webhook

功能说明

「帮你写一个 Webhook」弹窗支持用自然语言描述诉求，由系统生成一份配置初稿，之后可以随时调整。

前置条件

• 已准备好回调地址。

操作步骤

1. 在列表页点击「帮我写」，打开弹窗。
2. 填写「回调地址」（必填）；系统不会改动这个地址，会原样保留。
3. 按需填写「签名密钥」（可选，用于校验回调请求是否可信）。
4. 在「你想让 Webhook 做什么」（必填，1~1000 字）中描述诉求，例如「拦截所有 shell 命令，调用失败时拒绝执行」。描述越具体，初稿越贴近期望。
5. 点击「帮我搞定」，等待系统构思。
6. 在结果页查看把握度徽标（「把握较大 / 供你参考 / 建议多看一眼」）、「设计思路」「警告」和「配置草稿预览」：
   • 满意时点击「继续创建」，进入带「初稿」徽标的创建页，确认后保存；
   • 不满意时点击「再试一次」修改描述重新生成。

预期结果：初稿内容已填入创建页，可继续调整并点击「创建 Webhook」保存。

图 2-14：「帮你写一个 Webhook」弹窗——填写回调地址、可选签名密钥与诉求描述，点击「帮我搞定」生成初稿。

编辑与删除 Webhook

操作步骤（编辑）

1. 在列表中点击目标 Webhook 卡片，进入「编辑 Webhook」页，表单结构与创建页一致。
2. 已保存的签名密钥显示为掩码，点击眼睛图标可查看原值。
3. 修改后点击「保存更改」（没有改动时按钮置灰，提示「暂无修改」），成功后提示「Webhook 更新成功」。

操作步骤（删除）

1. 在编辑页右上角点击「…」→「删除 Webhook」，弹出「确认删除 Webhook」对话框，文案说明删除后该 Webhook 不再触发，并会从已挂载的智能体上移除，此操作不可撤销。
2. 点击「确认删除」，成功后提示「Webhook 删除成功」。

注意事项 / 异常处理

• Webhook 需在智能体详情中挂载后才会生效，只创建不挂载不会产生回调；预算配额通知类型则在预算策略中选用后生效。
• 应用级 Webhook 没有启停开关，也不配置执行顺序；需要暂停时可从智能体上取消挂载。租户级 Hook 的启停与执行顺序见事件管理。
• 回调地址不可达会导致投递失败，建议先通过「运行调试」验证连通性。