跳轉到主要內容
當一條防火牆規則傳回 pending_approval 時,工具呼叫會被保留,而你的 代理等待。預設情況下,一位審查者從主控台清除那個保留。防火牆 審批 webhook把同一個閘門接進你的系統:閘道在一個呼叫被保留的 那一刻 POST 一個簽署的通知到你的端點,而你的系統 POST 一個 HMAC 簽署的決定回來以釋放它——無需主控台席位、無需向一個人類輪詢。 這是人工介入的非同步（回呼）那一半。被保留的呼叫、裁決,以及主控台 解決路徑涵蓋於 解決審批與 防火牆參考;本頁 只是 webhook 的接線。
該 webhook 是一個快速路徑的提醒,而非記錄系統。中繼對被保留呼叫 的 long-poll 才是權威的閘門——如果一個通知被丟棄或你的接收器當機, 保留仍然成立,而一位審查者可以從主控台清除它。設定該 webhook 只是 增加了一個以程式方式解決它的途徑。

​
1. 何時使用一個防火牆審批 webhook

當一個人工介入的防火牆閘門必須由人類點擊一個按鈕以外的東西來解決 時,去拿它：

路由到你自己的審批 UI

把被保留的工具呼叫推進 Slack、PagerDuty 或一個內部審查佇列,並在 你的團隊已經工作的地方解決它們。

程式化政策

自動批准一個對著讀取副本的被保留 db.query、自動拒絕一個對著 prod 的——你的程式碼決定,閘道強制執行。

​
2. 在主控台中設定它

兩半都存在於一個工作區設定上。開啟 Firewall → Settings 並填入 兩個欄位（一項 Developer+ 動作——設定寫入是角色把關的）：
我們在一個呼叫被保留時 POST 到的 https:// 端點。HTTP 會被拒絕, 而該 URL 在儲存時會經過一個 SSRF 預檢,所以一個 loopback、私有 範圍,或 cloud-metadata 目的地會在它能被儲存之前被拒絕。將它留空 以完全停用非同步路徑。
一個唯寫的 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. 我們發送給你的通知

當一個呼叫被保留時,我們 POST 一個簽署的 JSON 信封到你的 URL： 
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（一個 防火牆閘道範圍的金鑰,而非 你的中繼金鑰或主控台工作階段）輪詢保留的狀態,直到它離開 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 從何而來,以及它如何與其他裁決組合。

閘道金鑰

鑄造輪詢 + 重新提交流程所需的防火牆閘道範圍金鑰。

過度代理權

人工介入閘門意在遏制的威脅。
關於裁決模型、強制執行介面,以及防火牆的其餘部分,參見 防火牆參考。