Zum Hauptinhalt springen
Wenn eine Firewall-Regel pending_approval zurückgibt, wird der Tool-Call zurückgehalten und Ihr Agent wartet. Standardmäßig räumt ein Prüfer diesen Hold aus der Konsole. Der Firewall-Approval-Webhook verdrahtet dasselbe Gate in Ihr System: das Gateway POSTet eine signierte Benachrichtigung an Ihren Endpunkt in dem Moment, in dem ein Aufruf zurückgehalten wird, und Ihr System POSTet eine HMAC-signierte Entscheidung zurück, um ihn freizugeben — kein Konsolen-Sitzplatz, kein Pollen eines Menschen. Dies ist die asynchrone (Callback-)Hälfte von Human-in-the-Loop. Der zurückgehaltene Aufruf, das Verdikt und der Konsolen-Auflösungspfad werden in Approvals auflösen und der Firewall-Referenz behandelt; diese Seite ist nur die Webhook-Verdrahtung.
Der Webhook ist ein Fast-Path-Hinweis, nicht das System of Record. Der Long-Poll des Relays auf dem zurückgehaltenen Aufruf ist das maßgebliche Gate — wenn eine Benachrichtigung verloren geht oder Ihr Empfänger ausfällt, bleibt der Hold bestehen, und ein Prüfer kann ihn aus der Konsole räumen. Das Konfigurieren des Webhooks fügt nur einen programmatischen Weg hinzu, ihn aufzulösen.

​
1. Wann ein Firewall-Approval-Webhook zu verwenden ist

Greifen Sie danach, wenn ein Human-in-the-Loop-Firewall-Gate von etwas anderem als einer Person aufgelöst werden muss, die einen Button klickt:

Zu Ihrer eigenen Approvals-UI routen

Schieben Sie zurückgehaltene Tool-Calls in Slack, PagerDuty oder eine interne Review-Queue und lösen Sie sie dort, wo Ihr Team bereits arbeitet.

Programmatische Policy

Genehmigen Sie automatisch einen zurückgehaltenen db.query gegen eine Read-Replica, lehnen Sie einen gegen prod automatisch ab — Ihr Code entscheidet, das Gateway setzt durch.

​
2. In der Konsole konfigurieren

Beide Hälften leben auf einer Workspace-Einstellung. Öffnen Sie Firewall → Settings und füllen Sie zwei Felder aus (eine Developer+-Aktion — der Settings-Write ist rollengesteuert):
Der https://-Endpunkt, an den wir POSTen, wenn ein Aufruf zurückgehalten wird. HTTP wird abgelehnt, und die URL wird beim Speichern durch einen SSRF-Preflight geführt, sodass ein Loopback-, Private-Range- oder Cloud-Metadata-Ziel abgewiesen wird, bevor es gespeichert werden kann. Lassen Sie es leer, um den asynchronen Pfad vollständig zu deaktivieren.
Ein write-only HMAC-Secret (bis zu 255 Zeichen). Es signiert unsere ausgehende Benachrichtigung und authentifiziert Ihren eingehenden Callback. Die Konsole echot es nie zurück — einmal gespeichert, sehen Sie nur, dass ein Secret gesetzt ist; rotieren Sie, indem Sie einen neuen Wert schreiben.
Der Callback-Endpunkt ist HMAC-only. Bis ein Shared Secret gesetzt ist, liefert das Gateway keine Benachrichtigungen aus und weist jeden Callback ab — das Gate kann nur aus der Konsole geräumt werden. Setzen Sie das Secret, um den asynchronen Pfad einzuschalten.
Lieber die REST-API? Dieselben Felder werden über die Konsolen-Settings-Route aktualisiert (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. Die Benachrichtigung, die wir Ihnen senden

Wenn ein Aufruf zurückgehalten wird, POSTen wir eine signierte JSON-Hülle an Ihre 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
  }
}
Die Hülle ist ein Routing-Signal, nicht der volle Kontext — sie trägt die approval_id, die Sie zum Auflösen brauchen, sowie Identifikatoren zur Korrelation, nie die Tool-Argumente. Das Argument-Detail lebt in der Approvals-Queue und im Firewall-Events-Log.
Verifizieren Sie die ausgehende Signatur, bevor Sie der Payload vertrauen: X-Orca-Signature ist sha256= + hex HMAC-SHA256(secret, raw_body) über die exakten Bytes, die Sie erhalten haben. Vergleichen Sie in konstanter Zeit. Die Auslieferung ist at-least-once und wird bei transienten Fehlern erneut versucht, machen Sie Ihren Handler also idempotent auf approval_id.

​
4. Der Callback, den Sie zurück-POSTen

Um den Hold freizugeben (oder abzulehnen), POSTen Sie Ihre Entscheidung an den Callback-Endpunkt mit der approval_id aus der Benachrichtigung: 
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 ist approved oder rejected — kein anderer Wert wird akzeptiert. reason ist optional und taucht im Audit-Trail des aufgelösten Approvals auf.
Die Callback-Signatur ist an die Approval-ID gebunden, sodass eine abgefangene Signatur nicht gegen einen anderen zurückgehaltenen Aufruf wiederholt werden kann. Signieren Sie den String <approval_id> + einen literalen Zeilenumbruch (\n) + den rohen Request-Body:
X-Orca-Signature = "sha256=" + HMAC_SHA256(secret, approval_id + "\n" + body)
Dies unterscheidet sich von der ausgehenden Benachrichtigung, die den Body allein signiert. Ein Callback, dessen Signatur nicht verifiziert, bekommt 401 — und eine fehlende, nicht übereinstimmende oder nicht existierende Approval-ID gibt dasselbe 401 zurück, sodass der Endpunkt nie bestätigt, ob eine ID existiert.
Der Callback ist first-decision-wins und idempotent: wer zuerst auflöst — Ihr Webhook oder ein Konsolen-Prüfer — setzt das Ergebnis, und ein wiederholter Callback für ein bereits aufgelöstes Approval gibt 200 zurück, sodass Ihr System aufhört, es erneut zu versuchen.

​
5. Den zurückgehaltenen Aufruf freigeben

Das Auflösen des Approvals wiederholt den Tool-Call nicht für Sie — es hebt das Gate, sodass Ihr Agent ihn erneut ausstellen kann. Die Agent-Runtime:
  1. Pollt den Zustand des Holds unter GET /api/v1/firewall/approvals/:id (ein firewall-gateway-scoped Key, nicht Ihr Relay-Key oder Ihre Konsolen-Session), bis er pending verlässt.
  2. Bei approved reicht er den ursprünglichen Tool-Call erneut ein, mit einem einmal nutzbaren X-OrcaRouter-Firewall-Approval-Header — das Gateway lässt diesen einen Aufruf durch und das Token ist verbraucht.
Wenn die zugrunde liegende Regel nach dem Zurückhalten des Aufrufs bearbeitet wurde, flaggt die Approvals-Queue, dass sich die Regel seitdem geändert hat, und unterdrückt die nun veraltete „held because…”-Klausel, sodass ein Konsolen-Prüfer nicht auf Provenienz handelt, die nicht mehr dem entspricht, was den Aufruf zurückgehalten hat.

​
6. Die Verdrahtung verifizieren

Eine schnelle End-to-End-Prüfung, bevor Sie sich darauf verlassen:
SchrittWas zu tun istErwartet
Einen Aufruf zurückhaltenEine Regel mit einem pending_approval-Verdikt auslösen400 firewall_approval_pending
BenachrichtigungIhren Endpunkt beobachtenSignierter firewall.approval.pending-POST trifft ein
CallbackEinen signierten { "decision": "approved" } POSTen200 mit dem aufgelösten Zustand
Replay-SchutzDen Callback erneut POSTen200, bereits aufgelöst (kein Double-Apply)
Wenn die Benachrichtigung nie eintrifft, bestätigen Sie, dass das Secret gesetzt ist (ohne es liefert das Gateway nicht) und dass die URL die HTTPS- + SSRF-Prüfungen zur Speicherzeit bestanden hat.

​
7. Wo das hineinpasst

Approvals auflösen

Der Konsolen-Prüferpfad und der vollständige Lebenszyklus eines zurückgehaltenen Aufrufs.

Verdikte

Woher pending_approval kommt und wie es sich mit anderen Verdikten komponiert.

Gateway-Keys

Prägen Sie den firewall-gateway-scoped Key, den der Poll- + Re-submit-Flow braucht.

Übermäßige Handlungsmacht

Die Bedrohung, die Human-in-the-Loop-Gates eindämmen sollen.
Für das Verdikt-Modell, die Enforcement-Surfaces und den Rest der Firewall siehe die Firewall-Referenz.