跳轉到主要內容
當防火牆規則返回 pending_approval 裁決時，閘道 保留工具呼叫並在頻道外通知你自己的審批系統。 那個通知是一個簽署的 HTTP POST——防火牆 webhook 負載——本頁記錄它的確切形狀，以便你可以驗證 簽名、路由事件，並回發你的決定。 這是防火牆頁面上描述的 控制台內審批流程的異步同胞。控制台路徑 （審查者點擊核准／拒絕）根本不需要 webhook。webhook 是 用於當你想要一個機器——你自己的工單機器人、Slack 動作，或 代理執行期——來解析保留的時候。兩條路徑都是先寫入者勝出，所以 你可以並排執行它們。
webhook 是一個盡力而為的路由訊號，而非權威的 HITL 頻道。代理自己對 GET /api/v1/firewall/approvals/:id 的長輪詢是後援——如果一個通知被丟棄或你的端點 短暫離線，被保留的呼叫仍會出現在控制台並正常 解析。webhook 只是讓機器能比人更快反應。

​
1. 防火牆 webhook 負載一覽

OrcaRouter 向你設定的 URL POST 一個 JSON 封套，以 共享密鑰簽署。這裡是一次完整的傳遞——標頭和主體： 
POST /your-approval-endpoint HTTP/1.1
Content-Type: application/json
X-Orca-Event: firewall.approval.pending
X-Orca-Signature: sha256=9f86d0818988...c2c9a3e1b4d7

{
  "event": "firewall.approval.pending",
  "workspace_id": 42,
  "occurred_at": "2026-06-09T12:00:00.123456789Z",
  "data": {
    "approval_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "tool_name": "db.export",
    "request_id": "req_01J9X...",
    "conversation_id": "conv_8f2a...",
    "policy_id": 7,
    "rule_id": 31
  }
}
這個封套與 OrcaRouter 為每個簽署事件使用的形狀相同，所以 一個接收器可以從 X-Orca-Event 路由多種事件類型而無需解析 主體。

​
2. 封套欄位

對於審批保留，總是 firewall.approval.pending。鏡像於 X-Orca-Event 標頭中，以便你可以在解析主體之前路由。
保留該呼叫的政策所屬工作區的整數 id。當 一個端點接收來自多個工作區的 webhook 時很有用。
閘道將審批排入佇列的時間的 RFC 3339 / UTC 時間戳記 （奈秒精度）。可被任何標準事件工具解析。
你的回呼解析閘門所需的區塊。欄位在 §3。

​
3. data 負載

data 區塊攜帶路由和解析保留所需的一切—— 刻意不含工具引數。webhook 是一個路由訊號； 完整的呼叫情境（工具、引數、觸發的規則）存在於控制台 Approvals 分頁和稽核日誌中，那裡有存取控制。
欄位類型含義
approval_idstring你回發決定所對應的 id。
tool_namestring被保留的工具，例如 db.export。
request_idstring觸發保留的中繼請求。
conversation_idstring代理對話／工作階段 id。
policy_idint匹配的防火牆政策。
rule_idint返回 pending_approval 的規則。
需要引數或匹配的子句來做決定？從控制台 Approvals 分頁讀取它們（Developer+），或讓你的代理用其閘道權杖輪詢 GET /api/v1/firewall/approvals/:id。webhook 刻意從不在線路上攜帶引數。

​
4. 驗證簽名

每次傳遞都被簽署，以便你可以拒絕偽造。簽名標頭 是： 
X-Orca-Signature: sha256=<hex HMAC-SHA256(secret, raw_body)>
其中 secret 是你在工作區上設定的審批 webhook 密鑰， 而 raw_body 是請求主體的確切位元組。在原始位元組上 計算 HMAC——重新序列化解析後的 JSON 會改變空白 並破壞比較。以常數時間驗證： 
import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)
外向 webhook 簽名只涵蓋主體。你回發的內向 回呼（§6）簽署 approval_id + 一個換行符 + 主體——一個不同的構造，是 刻意的，使得被擷取的簽名無法跨審批重放。不要 為兩個方向重用同一個簽署常式。

​
5. 設定 webhook

目的地 URL 和共享密鑰是工作區設定——在控制台中 設定一次（或透過設定 API；Developer+）。沒有營運人員介入， 也沒有東西要部署。
1

設定 URL 和密鑰

在防火牆設定中，把你的 HTTPS 端點設為審批 webhook URL，並設一個強的共享密鑰。URL 必須是 https://—— 明文目的地會被拒絕——且密鑰是唯寫的 （它在讀取時從不返回；設定回應只報告 是否已設定）。
2

撰寫一條 pending_approval 規則

新增一條裁決為 pending_approval 的防火牆規則（或使用 HITL 預設值）。參見防火牆規則。
3

接收並驗證

你的端點在下一次保留呼叫時接收簽署的 POST。驗證 簽名（§4），然後要麼透過回呼 解析，要麼呈現給人工。
被保留的呼叫在沒有設定 webhook 時仍然有效——它只是出現 在控制台供人工解析。而如果你設了 URL 但沒有密鑰， 閘道完全跳過派發，因為回呼端點 只接受簽署的請求：一個你無法驗證回來的通知 會毫無用處。

​
6. 回呼：解析保留

要以機器核准或拒絕，POST 回到： 
POST /api/v1/firewall/approvals/:id/callback
帶著你收到的作為 approval_id 的相同 :id，以相同的 共享密鑰簽署。主體是一個決定： 
BODY='{"decision":"approved","reason":"ticket OPS-4821 approved by on-call"}'
SIG="sha256=$(printf '%s\n%s' "$APPROVAL_ID" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')"

curl https://api.orcarouter.ai/api/v1/firewall/approvals/$APPROVAL_ID/callback \
  -H "Content-Type: application/json" \
  -H "X-Orca-Signature: $SIG" \
  -d "$BODY"
主體欄位必填值
decision是approved 或 rejected
reason否自由文字註記，記錄在稽核日誌中。
approved 決定讓代理的下一次嘗試通過一次—— 代理用單次使用的 X-OrcaRouter-Firewall-Approval 標頭重新提交 原始呼叫。rejected 決定讓呼叫保持 封鎖。
解析是冪等且先寫入者勝出的。如果人工已經 從控制台解析了保留——或一個重複的回呼到達—— 端點返回 200，附帶 already_resolved: true，原始 決定仍然成立。可安全重試。

​
7. 審批狀態

被保留的呼叫經過這些狀態；你的回呼驅動 離開 pending 的轉換：
狀態含義
pending等待決定（webhook 時的狀態）。
approved已解析——被閘控的呼叫可以進行一次。
rejected已解析——被閘控的呼叫保持封鎖。
expired保留在沒有決定的情況下逾時。

​
8. 相關參考

防火牆 — HITL 流程

pending_approval 如何保留呼叫，以及代理如何用 單次使用的審批標頭重新提交。

錯誤代碼

firewall_approval_pending 和其他防火牆 HTTP 回應。

裁決詞彙表

每個防火牆裁決，包括 pending_approval。

防火牆 API

完整的控制台 + 閘道路由參考。
關於保留如何融入更廣的控制模型，參見 強制執行模式和 危險的工具呼叫。