跳转到主要内容
当一条防火墙规则返回 pending_approval 时，该工具调用被挂起，而你的智能体 等待。默认情况下一名审查者从控制台清除那个挂起。防火墙审批 webhook 把 同一个门接入你的系统：在一个调用被挂起那一刻网关向你的端点 POST 一个签名 通知，而你的系统 POST 一个 HMAC 签名的决策回来以释放它——无需控制台席位， 无需轮询一名人工。 这是人工介入的异步（回调）那一半。被挂起的调用、判定和控制台解决路径在 解决审批 和 防火墙参考 中讲解；本页只讲 webhook 接线。
该 webhook 是一个快路径提醒，而非记录系统。中继对被挂起调用的长轮询才是 权威的门——如果一个通知被丢弃或你的接收器宕机，该挂起仍然成立，且一名审查者 能从控制台清除它。配置该 webhook 只是增加一种编程式的解决方式。

​
1. 何时使用一个防火墙审批 webhook

当一个人工介入的防火墙门必须由人点击按钮以外的东西来解决时使用它：

路由到你自己的审批 UI

把被挂起的工具调用推入 Slack、PagerDuty 或一个内部审查队列，并在你团队 已经工作的地方解决它们。

编程式策略

自动批准一个对只读副本的被挂起 db.query，自动拒绝一个对 prod 的 ——你的代码决定，网关执行。

​
2. 在控制台中配置它

两半都存在于一个工作区设置上。打开 Firewall → Settings 并填入两个字段 （一个 Developer+ 操作——设置写入是角色门控的）：
在一个调用被挂起时我们 POST 到的 https:// 端点。HTTP 被拒绝，而该 URL 在保存时被跑过一个 SSRF 预检，所以一个回环、私有范围或云元数据目的地 在它能被存储之前就被拒绝。把它留空以完全禁用异步路径。
一个只写的 HMAC 密钥（最多 255 个字符）。它签署我们的出站通知并认证 你的入站回调。控制台从不回显它——一旦保存你只看到一个密钥已设置；通过 写入一个新值来轮换。
回调端点是 HMAC 唯一。在一个共享密钥被设置之前，网关不会投递通知并拒绝 每一个回调——该门只能从控制台清除。设置该密钥以打开异步路径。
更喜欢 REST API？同样的字段通过控制台设置路由更新（UserAuth，Developer+）： 
curl -X PUT https://api.orcarouter.ai/api/workspace/firewall/settings \
  -H "Authorization: Bearer $ORCA_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "approval_webhook_url": "https://hooks.example.com/orca/firewall",
        "approval_webhook_secret": "whsec_your_shared_secret"
      }'

​
3. 我们发给你的通知

当一个调用被挂起时，我们向你的 URL POST 一个签名的 JSON 信封： 
POST /orca/firewall HTTP/1.1
Content-Type: application/json
X-Orca-Event: firewall.approval.pending
X-Orca-Signature: sha256=<hex>

{
  "event": "firewall.approval.pending",
  "workspace_id": 42,
  "occurred_at": "2026-06-09T17:04:11.482Z",
  "data": {
    "approval_id": "665f1b...",
    "tool_name": "db.query",
    "request_id": "req_9f2c...",
    "conversation_id": "conv_77a1...",
    "policy_id": 7,
    "rule_id": 31
  }
}
该信封是一个路由信号，而非完整上下文——它携带你解决所需的 approval_id 和用于关联的标识符，绝不携带工具参数。参数细节存在于 Approvals 队列 和防火墙 事件日志 中。
在你信任载荷之前验证出站签名：X-Orca-Signature 是 sha256= + 对你收到的 确切字节的十六进制 HMAC-SHA256(secret, raw_body)。以常量时间比较。投递是 至少一次的并在瞬时失败时重试，所以让你的处理器对 approval_id 幂等。

​
4. 你 POST 回来的回调

要释放（或拒绝）该挂起，用通知中的 approval_id 把你的决策 POST 到回调 端点： 
POST /api/v1/firewall/approvals/665f1b.../callback
X-Orca-Signature: sha256=<hex>
Content-Type: application/json

{ "decision": "approved", "reason": "read-replica query, auto-approved" }
decision 是 approved 或 rejected——不接受其他值。reason 是可选的， 并显示在已解决审批的审计追踪上。
回调签名绑定到审批 id，所以一个被捕获的签名无法对一个不同的被挂起调用 重放。签署字符串 <approval_id> + 一个字面换行符（\n）+ 原始请求体：
X-Orca-Signature = "sha256=" + HMAC_SHA256(secret, approval_id + "\n" + body)
这与出站通知不同，后者只签署请求体。一个签名验证不通过的回调得到 401——而一个缺失、不匹配或不存在的审批 id 返回同样的 401，所以该端点 绝不确认一个 id 是否存在。
该回调是首个决策生效且幂等的：谁先解决——你的 webhook 或一名控制台 审查者——谁就设定结果，而对一个已解决审批的一次重复回调返回 200，这样 你的系统停止重试。

​
5. 释放被挂起的调用

解决该审批不会为你重放该工具调用——它解除该门，这样你的智能体能重新发出 它。智能体运行时：
  1. 在 GET /api/v1/firewall/approvals/:id（一个 firewall-gateway-scoped 密钥，而非 你的中继密钥或控制台会话）上轮询该挂起的状态，直到它离开 pending。
  2. 在 approved 时，重新提交携带一个一次性 X-OrcaRouter-Firewall-Approval 头的原始工具调用——网关放那一次调用通过 且该令牌被消耗。
如果底层规则在该调用被挂起之后被编辑过， Approvals 队列 会标记该规则此后 已改变并抑制现已陈旧的 “held because…” 子句，这样一名控制台审查者不会根据 一个不再匹配实际挂起该调用的来源行事。

​
6. 验证接线

在你依赖它之前做一次快速的端到端检查：
步骤怎么做预期
挂起一个调用触发一条带 pending_approval 判定的规则400 firewall_approval_pending
通知观察你的端点签名的 firewall.approval.pending POST 到达
回调POST 一个签名的 { "decision": "approved" }200，带已解决状态
重放守卫再次 POST 该回调200，已解决（无双重应用）
如果通知从不到达，确认密钥已设置（没有它网关不会投递），且该 URL 在保存时 通过了 HTTPS + SSRF 检查。

​
7. 这部分的位置

解决审批

控制台审查者路径和完整的被挂起调用生命周期。

判定

pending_approval 从何而来以及它如何与其他判定组合。

网关密钥

铸造轮询 + 重新提交流程所需的 firewall-gateway-scoped 密钥。

过度代理

人工介入门意在遏制的威胁。
关于判定模型、执行面以及防火墙的其余部分，参见 防火墙参考。