메인 콘텐츠로 건너뛰기
firewall 규칙이 pending_approval을 반환하면, 툴 호출이 보류되고 에이전트가 기다립니다. 기본적으로 검토자가 콘솔에서 그 보류를 해소합니다. firewall 승인 웹훅은 같은 게이트를 당신의 시스템에 배선합니다: 게이트웨이가 호출이 보류되는 순간 당신의 엔드포인트로 서명된 알림을 POST하고, 당신의 시스템이 그것을 해제하기 위해 HMAC 서명 결정을 다시 POST합니다 — 콘솔 좌석 없음, 사람 폴링 없음. 이것은 human-in-the-loop의 비동기(콜백) 절반입니다. 보류된 호출, 판정, 그리고 콘솔 해결 경로는 승인 해결과 Firewall 레퍼런스에서 다룹니다; 이 페이지는 그저 웹훅 배선입니다.
웹훅은 시스템 오브 레코드가 아니라 빠른 경로 사전 통지입니다. 보류된 호출에 대한 릴레이의 long-poll이 권위 있는 게이트입니다 — 알림이 드롭되거나 수신기가 다운되어도, 보류는 여전히 유지되고 검토자가 콘솔에서 그것을 해소할 수 있습니다. 웹훅을 구성하는 것은 그것을 해결하는 프로그램적 방법을 추가할 뿐입니다.

​
1. 언제 firewall 승인 웹훅을 사용하는가

human-in-the-loop firewall 게이트가 버튼을 클릭하는 사람이 아닌 다른 무언가에 의해 해결되어야 할 때 사용하세요:

자체 승인 UI로 라우팅

보류된 툴 호출을 Slack, PagerDuty, 또는 내부 검토 큐로 푸시하고 팀이 이미 작업하는 곳에서 해결합니다.

프로그램적 정책

읽기 레플리카에 대한 보류된 db.query을 자동 승인하고, prod에 대한 것은 자동 거부 — 코드가 결정하고, 게이트웨이가 강제합니다.

​
2. 콘솔에서 구성하기

두 절반은 하나의 워크스페이스 설정에 존재합니다. Firewall → Settings를 열고 두 필드를 채우세요(Developer+ 액션 — 설정 쓰기는 역할 게이트됨):
호출이 보류될 때 우리가 POST하는 https:// 엔드포인트. HTTP는 거부되고, URL은 저장 시 SSRF 사전 점검을 거치므로, loopback, 사설 범위, 또는 클라우드 메타데이터 목적지는 저장되기 전에 거부됩니다. 비동기 경로를 완전히 비활성화하려면 비워두세요.
쓰기 전용 HMAC 시크릿(최대 255자). 그것은 우리의 아웃바운드 알림에 서명하고 그리고 당신의 인바운드 콜백을 인증합니다. 콘솔은 그것을 결코 다시 echo하지 않습니다 — 일단 저장되면 시크릿이 설정되어 있다는 것만 보입니다; 새 값을 써서 회전하세요.
콜백 엔드포인트는 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. 우리가 당신에게 보내는 알림

호출이 보류되면, 우리는 당신의 URL로 서명된 JSON 봉투를 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 큐와 firewall 이벤트 로그에 존재합니다.
페이로드를 신뢰하기 전에 아웃바운드 서명을 검증하세요: 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가 존재하는지 결코 확인하지 않습니다.
콜백은 first-decision-wins이고 멱등적입니다: 먼저 해결하는 쪽이 — 당신의 웹훅이든 콘솔 검토자든 — 결과를 설정하고, 이미 해결된 승인에 대한 반복 콜백은 200을 반환하므로 당신의 시스템이 재시도를 멈춥니다.

​
5. 보류된 호출 해제하기

승인을 해결하는 것이 툴 호출을 당신을 위해 재생하지는 않습니다 — 에이전트가 그것을 재발행할 수 있도록 게이트를 들어 올립니다. 에이전트 런타임은:
  1. GET /api/v1/firewall/approvals/:id에서 보류의 상태를 폴링합니다(firewall-gateway-scoped 키, 당신의 릴레이 키나 콘솔 세션이 아님), 그것이 pending을 떠날 때까지.
  2. approved에서, 일회용 X-OrcaRouter-Firewall-Approval 헤더를 담아 원래 툴 호출을 재제출합니다 — 게이트웨이가 그 한 호출을 통과시키고 토큰이 소비됩니다.
호출이 보류된 후 기저 규칙이 편집되면, Approvals 큐는 규칙이 그 후 변경되었음을 플래그하고 이제 오래된 “held because…” 절을 억제하므로, 콘솔 검토자가 호출을 보류한 것과 더 이상 매치하지 않는 출처에 따라 행동하지 않습니다.

​
6. 배선 확인

의존하기 전에 빠른 엔드투엔드 점검:
단계할 일예상
호출 보류pending_approval 판정을 가진 규칙 트리거400 firewall_approval_pending
알림엔드포인트 관찰서명된 firewall.approval.pending POST 도착
콜백서명된 { "decision": "approved" } POST해결된 상태와 함께 200
재생 가드콜백을 다시 POST200, 이미 해결됨(이중 적용 없음)
알림이 도착하지 않으면, 시크릿이 설정되었는지(없으면 게이트웨이가 전달하지 않음) 그리고 URL이 저장 시점에 HTTPS + SSRF 검사를 통과했는지 확인하세요.

​
7. 이것이 어디에 들어맞는가

승인 해결

콘솔 검토자 경로와 전체 보류 호출 수명 주기.

Verdicts

pending_approval이 어디서 오고 다른 판정과 어떻게 조합되는가.

게이트웨이 키

폴 + 재제출 흐름에 필요한 firewall-gateway-scoped 키를 발행합니다.

과도한 자율성

human-in-the-loop 게이트가 봉쇄하도록 구축된 위협.
판정 모델, 강제 표면, 그리고 firewall의 나머지는 Firewall 레퍼런스를 참조하세요.