メインコンテンツへスキップ
ファイアウォールルールが pending_approval を返すと、ツール呼び出しが保留され、 エージェントが待ちます。デフォルトでは、レビュアーがコンソールからその保留をクリアします。 ファイアウォール承認 webhook は同じゲートをあなたのシステムに配線します：呼び出しが 保留された瞬間にゲートウェイがあなたのエンドポイントに署名付き通知を POST し、あなたの システムがそれを解放するために HMAC 署名付き決定を POST して返します — コンソールの 席なし、人間のポーリングなし。 これはヒューマンインザループの非同期（コールバック）半分です。保留された呼び出し、判定、 コンソールの解決パスは承認の解決と ファイアウォールリファレンスで カバーされています；このページは webhook の配線だけです。
webhook はファストパスの先触れであり、記録のシステムではありません。保留された 呼び出しに対するリレーのロングポールが権威あるゲートです — 通知がドロップされたり受信側が ダウンしたりしても、保留は依然として有効で、レビュアーがコンソールからそれをクリア できます。webhook の設定は、それを解決するプログラム的な方法を追加するだけです。

​
1. いつファイアウォール承認 webhook を使うか

ヒューマンインザループのファイアウォールゲートが、ボタンをクリックする人以外の何かで 解決されなければならないときに手を伸ばします：

独自の承認 UI にルーティング

保留されたツール呼び出しを Slack、PagerDuty、または内部レビューキューにプッシュし、 チームがすでに作業している場所でそれらを解決します。

プログラム的なポリシー

リードレプリカに対する保留された db.query を自動承認し、prod に対するものを 自動拒否 — あなたのコードが決定し、ゲートウェイが強制します。

​
2. コンソールで設定する

両半分はひとつのワークスペース設定に存在します。Firewall → Settings を開き、2 つの フィールドを記入します（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. 私たちがあなたに送る通知

呼び出しが保留されると、私たちは署名付き JSON エンベロープをあなたの URL に POST します： 
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 キューと ファイアウォールevents ログに存在します。
ペイロードを信頼する前にアウトバウンド署名を検証します：X-Orca-Signature は sha256= + あなたが受け取った正確なバイトに対する hex HMAC-SHA256(secret, raw_body) です。定数時間で比較します。配信は at-least-once で一時的な失敗時に再試行されるため、 ハンドラを 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 ヘッダーを運んで元の ツール呼び出しを再送信します — ゲートウェイはその 1 つの呼び出しを通し、 トークンが消費されます。
呼び出しが保留された後に基礎となるルールが編集された場合、 Approvals キューはルールがその後変更された ことをフラグし、今や古くなった「held because…」句を抑制するため、コンソールの レビュアーが呼び出しを保留したものにもはやマッチしない来歴に基づいて行動することは ありません。

​
6. 配線を検証する

依存する前のクイックなエンドツーエンドチェック：
ステップ何をするか期待される結果
呼び出しを保留pending_approval 判定のルールをトリガー400 firewall_approval_pending
通知エンドポイントを監視署名付き firewall.approval.pending POST が到着
コールバック署名付きの { "decision": "approved" } を POST解決された状態とともに 200
リプレイガードコールバックを再度 POST200、すでに解決済み（二重適用なし）
通知が決して到着しない場合、シークレットが設定されていること（それなしではゲートウェイは 配信しません）と、URL が保存時に HTTPS + SSRF チェックを通過したことを確認します。

​
7. これがどこに収まるか

承認の解決

コンソールレビュアーのパスと完全な保留呼び出しのライフサイクル。

判定

pending_approval がどこから来るか、そして他の判定とどう合成されるか。

ゲートウェイキー

ポーリング + 再送信フローが必要とするファイアウォールゲートウェイスコープのキーを発行。

過剰なエージェンシー

ヒューマンインザループのゲートが封じ込めるために作られた脅威。
判定モデル、強制サーフェス、そしてファイアウォールの残りについては、 ファイアウォールリファレンスを参照してください。