# Webhook

在当前应用下创建 Webhook，捕捉 Agent 执行过程与预算用量的关键事件

## 查看 Webhook 列表

**功能说明**

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

| 类型 | 列表徽标 | 投递方式 | 如何生效 |
| --- | --- | --- | --- |
| 拦截型 | 拦截型 | 同步等待回调服务返回放行 / 拒绝 / 修改决策 | 在[智能体详情](/docs/tenant-portal/agents.md#agent-detail)的「Webhook」卡片中挂载 |
| 观察型 | 观察型 | 异步投递，只需返回 2xx | 在智能体详情的「Webhook」卡片中挂载 |
| 预算配额通知 | 配额型 | 异步投递 | 在[预算策略](/docs/tenant-portal/quota.md#policy-crud)的「用量通知」中选用，不能挂载到智能体 |

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

**前置条件**

- 已进入目标应用空间。

**操作步骤**

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

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

![Webhook 列表](/docs/images/tenant-portal/13-webhooks-list.png)

*图 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 地址，路径和查询参数支持[运行时变量](#runtime-variables)超时（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](#debug-webhook)。
7. 确认无误后点击右上角「创建 Webhook」；如需放弃，点击「取消」。

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

![Webhook 手动创建表单](/docs/images/tenant-portal/51-webhook-create-form.png)

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

> 表单有未保存的改动（顶部显示「未保存」徽标）时离开页面，系统会弹出离开确认。确认离开后未保存的内容将丢失，请先点击「创建 Webhook」保存。

## 在 Webhook 中使用运行时变量

**功能说明**

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

| 变量 | 含义 |
| --- | --- |
| `${sys.principalId}` | 当前用户 ID（系统提供，不可伪造） |
| `${sys.sessionId}` | 会话 ID |
| `${sys.agentId}` | 智能体 ID |
| `${sys.requestId}` | 请求 ID |
| `${ctx.自定义名}` | 由调用方在请求的 `runtimeVariables` 参数中传入 |

示例回调地址：`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」保存。

![帮我写 Webhook 弹窗](/docs/images/tenant-portal/52-webhook-ai-generate.png)

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

## 编辑与删除 Webhook

**操作步骤（编辑）**

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

**操作步骤（删除）**

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

**注意事项 / 异常处理**

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