メインコンテンツへスキップ
ファイアウォールルールが pending_approval 判定を返すと、ゲートウェイはツール呼び出しを 保留し、あなた自身の承認システムに帯域外で通知します。その通知は署名付きの HTTP POST — ファイアウォール webhook ペイロード — であり、このページはその正確な形状を ドキュメント化しているため、署名を検証し、イベントをルーティングし、決定をポストバック できます。 これは、ファイアウォールページで説明されて いるコンソール内承認フローの非同期の兄弟です。コンソールパス（レビュアーが承認/拒否を クリックする）は webhook をまったく必要としません。webhook は、保留を解決するために マシン — あなた自身のチケットボット、Slack アクション、エージェントランタイム — を 使いたいときのためのものです。両方のパスはファーストライタウィンなので、並行して 実行できます。
webhook はベストエフォートのルーティングシグナルであり、権威ある HITL チャネルでは ありません。エージェント自身の GET /api/v1/firewall/approvals/:id へのロングポールがバックストップです — 通知がドロップされたり、エンドポイントが 一時的にダウンしても、保留された呼び出しは依然としてコンソールに表示され、通常通り 解決されます。webhook は、マシンが人間より速く反応できるようにするだけです。

​
1. ファイアウォール webhook ペイロード一覧

OrcaRouter は、あなたが設定した URL に JSON エンベロープを POST し、共有シークレットで 署名します。完全な配信 — ヘッダーとボディ — は次のとおりです： 
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_idintpending_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 /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 の決定は、呼び出しをブロックしたままにします。
解決は冪等かつファーストライタウィンです。人間がすでにコンソールから保留を解決 していた場合 — あるいは重複したコールバックが到着した場合 — エンドポイントは already_resolved: true とともに 200 を返し、元の決定が有効なままです。リトライ しても安全です。

​
7. 承認状態

保留された呼び出しは、これらの状態を経て移行します；あなたのコールバックが pending からの遷移を駆動します：
状態意味
pending決定待ち（webhook 時点の状態）。
approved解決済み — ゲートされた呼び出しは一度だけ進められます。
rejected解決済み — ゲートされた呼び出しはブロックされたままです。
expired保留が決定なしで期限切れになりました。

​
8. 関連リファレンス

ファイアウォール — HITL フロー

pending_approval がどう呼び出しを保留し、エージェントが単回使用の承認ヘッダーで どう再送信するか。

エラーコード

firewall_approval_pending とその他のファイアウォール HTTP レスポンス。

判定用語集

pending_approval を含む、すべてのファイアウォール判定。

ファイアウォール API

完全なコンソール + ゲートウェイルートリファレンス。
保留がより広いコントロールモデルにどう適合するかについては、 強制モードと 危険なツール呼び出しを参照してください。