Przejdź do głównej treści
Gdy reguła firewalla zwraca pending_approval, wywołanie narzędzia jest wstrzymane, a twój agent czeka. Domyślnie recenzent czyści to wstrzymanie z konsoli. Webhook zatwierdzeń firewalla okablowuje tę samą bramę w twój system: brama wysyła POST z podpisanym powiadomieniem na twój endpoint w momencie wstrzymania wywołania, a twój system wysyła POST z podpisaną HMAC decyzją z powrotem, by je zwolnić — bez fotela w konsoli, bez odpytywania człowieka. To asynchroniczna (callback) połowa człowieka w pętli. Wstrzymane wywołanie, werdykt i ścieżka rozstrzygania w konsoli są omówione w Rozstrzygaj zatwierdzenia i referencji Firewall; ta strona to tylko okablowanie webhooka.
Webhook to szybkościeżkowe uprzedzenie, nie system rekordu. Długie odpytywanie relay na wstrzymanym wywołaniu to autorytatywna brama — jeśli powiadomienie zostanie zgubione lub twój odbiornik jest wyłączony, wstrzymanie wciąż obowiązuje, a recenzent może je wyczyścić z konsoli. Skonfigurowanie webhooka tylko dodaje programowy sposób na rozstrzygnięcie go.

​
1. Kiedy używać webhooka zatwierdzeń firewalla

Sięgnij po niego, gdy brama firewalla człowieka w pętli musi być rozstrzygnięta przez coś innego niż człowieka klikającego przycisk:

Kieruj do własnego UI zatwierdzeń

Wypchnij wstrzymane wywołania narzędzi do Slacka, PagerDuty lub wewnętrznej kolejki przeglądu i rozstrzygaj je tam, gdzie twój zespół już pracuje.

Polityka programowa

Auto-zatwierdź wstrzymane db.query wobec repliki do odczytu, auto-odrzuć wobec prod — twój kod decyduje, brama egzekwuje.

​
2. Skonfiguruj to w konsoli

Obie połowy żyją na jednym ustawieniu przestrzeni roboczej. Otwórz Firewall → Settings i wypełnij dwa pola (akcja Developer+ — zapis ustawień jest bramkowany rolą):
Endpoint https://, na który wysyłamy POST, gdy wywołanie jest wstrzymane. HTTP jest odmawiane, a URL jest przepuszczany przez preflight SSRF przy zapisie, więc cel loopback, prywatnego zakresu lub metadanych chmury jest odrzucany, zanim będzie mógł zostać zapisany. Zostaw je puste, aby całkowicie wyłączyć ścieżkę asynchroniczną.
Tylko-do-zapisu sekret HMAC (do 255 znaków). Podpisuje nasze wychodzące powiadomienie oraz uwierzytelnia twój przychodzący callback. Konsola nigdy nie odbija go z powrotem — po zapisie widzisz tylko, że sekret jest ustawiony; rotuj, zapisując nową wartość.
Endpoint callbacku jest tylko-HMAC. Dopóki współdzielony sekret nie jest ustawiony, brama nie dostarczy powiadomień i odrzuca każdy callback — bramę można wyczyścić tylko z konsoli. Ustaw sekret, aby włączyć ścieżkę asynchroniczną.
Wolisz API REST? Te same pola aktualizują się przez trasę ustawień konsoli (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. Powiadomienie, które ci wysyłamy

Gdy wywołanie jest wstrzymane, wysyłamy POST z podpisaną kopertą JSON na twój 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
  }
}
Koperta to sygnał kierowania, nie pełny kontekst — niesie approval_id, którego potrzebujesz do rozstrzygnięcia, i identyfikatory do korelacji, nigdy argumenty narzędzia. Szczegół argumentów żyje w kolejce Approvals i logu zdarzeń firewalla.
Zweryfikuj podpis wychodzący, zanim zaufasz ładunkowi: X-Orca-Signature to sha256= + hex HMAC-SHA256(secret, raw_body) nad dokładnymi bajtami, które otrzymałeś. Porównaj w stałym czasie. Dostarczenie jest co-najmniej-raz i ponawiane przy przejściowych awariach, więc uczyń swój handler idempotentnym na approval_id.

​
4. Callback, który wysyłasz z powrotem

Aby zwolnić (lub odrzucić) wstrzymanie, wyślij POST ze swoją decyzją na endpoint callbacku z approval_id z powiadomienia: 
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 to approved lub rejected — żadna inna wartość nie jest akceptowana. reason jest opcjonalny i pojawia się na śladzie audytu rozstrzygniętego zatwierdzenia.
Podpis callbacku jest związany z id zatwierdzenia, więc przechwycony podpis nie może być odtworzony wobec innego wstrzymanego wywołania. Podpisz string <approval_id> + dosłowny znak nowej linii (\n) + surowe ciało żądania:
X-Orca-Signature = "sha256=" + HMAC_SHA256(secret, approval_id + "\n" + body)
To różni się od wychodzącego powiadomienia, które podpisuje samo ciało. Callback, którego podpis się nie weryfikuje, dostaje 401 — a brakujące, niezgodne lub nieistniejące id zatwierdzenia zwraca to samo 401, więc endpoint nigdy nie potwierdza, czy id istnieje.
Callback jest wygrywa-pierwsza-decyzja i idempotentny: kto rozstrzyga pierwszy — twój webhook czy recenzent konsoli — ustawia wynik, a powtórzony callback dla już-rozstrzygniętego zatwierdzenia zwraca 200, więc twój system przestaje ponawiać.

​
5. Zwalnianie wstrzymanego wywołania

Rozstrzygnięcie zatwierdzenia nie odtwarza wywołania narzędzia za ciebie — podnosi bramę, by twój agent mógł je ponownie wystawić. Środowisko uruchomieniowe agenta:
  1. Odpytuje stan wstrzymania pod GET /api/v1/firewall/approvals/:id (klucz w zakresie firewall-gateway, nie twój klucz relay ani sesja konsoli), aż opuści pending.
  2. Na approved ponownie wysyła oryginalne wywołanie narzędzia niosące jednorazowy nagłówek X-OrcaRouter-Firewall-Approval — brama przepuszcza to jedno wywołanie, a token jest zużyty.
Jeśli reguła podstawowa została edytowana po wstrzymaniu wywołania, kolejka Approvals flaguje, że reguła od tego czasu się zmieniła, i tłumi teraz-nieaktualną klauzulę „wstrzymane, ponieważ…”, więc recenzent konsoli nie działa na proweniencji, która już nie pasuje do tego, co wstrzymało wywołanie.

​
6. Zweryfikuj okablowanie

Szybkie sprawdzenie end-to-end, zanim na nim polegniesz:
KrokCo zrobićOczekiwane
Wstrzymaj wywołanieUruchom regułę z werdyktem pending_approval400 firewall_approval_pending
PowiadomienieObserwuj swój endpointPrzybywa podpisany POST firewall.approval.pending
CallbackWyślij POST podpisany { "decision": "approved" }200 z rozstrzygniętym stanem
Strażnik powtórzeńWyślij callback ponownie200, już rozstrzygnięte (bez podwójnego zastosowania)
Jeśli powiadomienie nigdy nie przybywa, potwierdź, że sekret jest ustawiony (bez niego brama nie dostarczy) i że URL przeszedł sprawdzenia HTTPS + SSRF w czasie zapisu.

​
7. Gdzie to pasuje

Rozstrzygaj zatwierdzenia

Ścieżka recenzenta w konsoli i pełny cykl życia wstrzymanego wywołania.

Werdykty

Skąd bierze się pending_approval i jak komponuje się z innymi werdyktami.

Klucze gateway

Wybij klucz w zakresie firewall-gateway, którego potrzebuje przepływ odpytaj + wyślij ponownie.

Nadmierna sprawczość

Zagrożenie, które bramy człowieka w pętli mają powstrzymywać.
Dla modelu werdyktów, powierzchni egzekwowania i reszty firewalla zobacz referencję Firewall.