메인 콘텐츠로 건너뛰기
Firewall 규칙이 pending_approval 판정을 반환하면, 게이트웨이는 툴 호출을 보류하고 여러분 자신의 승인 시스템에 대역 외로 알립니다. 그 알림은 서명된 HTTP POST — firewall 웹훅 페이로드 — 이며, 이 페이지는 여러분이 서명을 검증하고, 이벤트를 라우팅하고, 결정을 되돌려 포스트할 수 있도록 그 정확한 형태를 문서화합니다. 이것은 Firewall 페이지에 설명된 콘솔 내 승인 흐름의 비동기 형제입니다. 콘솔 경로(검토자가 승인/거부를 클릭)는 웹훅이 전혀 필요 없습니다. 웹훅은 머신 — 여러분 자신의 티켓팅 봇, Slack 액션, 또는 에이전트 런타임 — 이 보류를 해결하길 원할 때를 위한 것입니다. 두 경로 모두 first-writer-wins이므로, 나란히 실행할 수 있습니다.
웹훅은 권위 있는 HITL 채널이 아니라 최선 노력 라우팅 신호입니다. 에이전트 자신의 GET /api/v1/firewall/approvals/:id에 대한 롱 폴이 백스톱입니다 — 알림이 누락되거나 여러분의 엔드포인트가 잠시 다운되어도, 보류된 호출은 여전히 콘솔에 표면화되고 정상적으로 해결됩니다. 웹훅은 그저 머신이 사람보다 빠르게 반응하게 합니다.

​
1. firewall 웹훅 페이로드 한눈에 보기

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. 하나의 엔드포인트가 여러 워크스페이스에서 웹훅을 받을 때 유용합니다.
게이트웨이가 승인을 큐에 넣은 시각의 RFC 3339 / UTC 타임스탬프(나노초 정밀도). 임의의 표준 이벤트 도구로 파싱 가능합니다.
콜백이 게이트를 해결하는 데 필요한 블록. 필드는 §3에 있습니다.

​
3. data 페이로드

data 블록은 보류를 라우팅하고 해결하는 데 필요한 모든 것을 담습니다 — 의도적으로 툴 인자는 없음. 웹훅은 라우팅 신호입니다; 전체 호출 컨텍스트 (툴, 인자, 발동한 규칙)는 콘솔 Approvals 탭과 감사 로그에 있으며, 거기서 접근 제어됩니다.
FieldTypeMeaning
approval_idstring여러분이 결정을 포스트하는 대상 id.
tool_namestring보류된 툴, 예: db.export.
request_idstring보류를 유발한 릴레이 요청.
conversation_idstring에이전트 대화 / 세션 id.
policy_idint매치된 firewall 정책.
rule_idintpending_approval을 반환한 규칙.
결정을 내리기 위해 인자나 매치된 절이 필요한가요? 콘솔 Approvals 탭(Developer+)에서 읽거나, 에이전트가 게이트웨이 토큰으로 GET /api/v1/firewall/approvals/:id를 폴링하게 하세요. 웹훅은 의도적으로 인자를 와이어로 결코 전달하지 않습니다.

​
4. 서명 검증하기

모든 전달은 위조를 거부할 수 있도록 서명됩니다. 서명 헤더는: 
X-Orca-Signature: sha256=<hex HMAC-SHA256(secret, raw_body)>
여기서 secret은 여러분이 워크스페이스에 설정한 승인 웹훅 시크릿이고 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)
아웃바운드 웹훅 서명은 본문만을 다룹니다. 여러분이 되돌려 포스트하는 인바운드 콜백(§6)은 approval_id + 개행 + 본문을 서명합니다 — 의도적으로 다른 구성이므로, 캡처된 서명이 여러 승인에 걸쳐 재생될 수 없습니다. 한 서명 루틴을 양방향에 재사용하지 마세요.

​
5. 웹훅 구성하기

목적지 URL과 공유 시크릿은 워크스페이스 설정입니다 — 콘솔에서(또는 설정 API를 통해; Developer+) 한 번 설정하세요. 운영자 개입이 없고 배포할 것이 없습니다.
1

URL과 시크릿을 설정한다

Firewall 설정에서 여러분의 HTTPS 엔드포인트를 승인 웹훅 URL로, 그리고 강력한 공유 시크릿을 설정하세요. URL은 https://여야 합니다 — 평문 목적지는 거부됩니다 — 그리고 시크릿은 쓰기 전용입니다(읽을 때 결코 반환되지 않습니다; 설정 응답은 하나가 설정되었는지만 보고합니다).
2

pending_approval 규칙을 작성한다

판정이 pending_approval인 Firewall 규칙을 추가하세요(또는 HITL 프리셋을 사용하세요). Firewall 규칙 참조.
3

수신하고 검증한다

여러분의 엔드포인트는 다음 보류된 호출에서 서명된 POST를 받습니다. 서명을 검증하고(§4), 그 다음 콜백을 통해 해결하거나 사람을 위해 표면화하세요.
보류된 호출은 웹훅이 전혀 구성되지 않아도 여전히 작동합니다 — 그저 사람이 해결하도록 콘솔에 나타날 뿐입니다. 그리고 URL은 설정하되 시크릿은 설정하지 않으면, 콜백 엔드포인트가 서명된 요청만 받아들이기 때문에 게이트웨이는 디스패치를 전적으로 건너뜁니다: 여러분이 되돌려 인증할 수 없는 알림은 쓸모없을 것입니다.

​
6. 콜백: 보류 해결하기

머신으로 승인 또는 거부하려면, 되돌려 POST하세요: 
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"
Body fieldRequiredValues
decisionyesapproved 또는 rejected
reasonno자유 텍스트 노트, 감사 로그에 기록됨.
approved 결정은 에이전트의 다음 시도를 한 번 통과시킵니다 — 에이전트는 일회용 X-OrcaRouter-Firewall-Approval 헤더와 함께 원래 호출을 재제출합니다. rejected 결정은 호출을 차단된 채로 유지합니다.
해결은 멱등적이며 first-writer-wins입니다. 사람이 이미 콘솔에서 보류를 해결했거나 — 또는 중복 콜백이 도착하면 — 엔드포인트는 already_resolved: true와 함께 200을 반환하고 원래 결정이 유지됩니다. 재시도해도 안전합니다.

​
7. 승인 상태

보류된 호출은 이 상태들을 거칩니다; 여러분의 콜백이 pending에서 벗어나는 전이를 구동합니다:
StateMeaning
pending결정 대기 중(웹훅 시점의 상태).
approved해결됨 — 게이트된 호출이 한 번 진행할 수 있음.
rejected해결됨 — 게이트된 호출이 차단된 채로 유지됨.
expired보류가 결정 없이 만료됨.

​
8. 관련 레퍼런스

Firewall — HITL 흐름

pending_approval이 호출을 어떻게 보류하고 에이전트가 일회용 승인 헤더와 함께 어떻게 재제출하는지.

오류 코드

firewall_approval_pending과 다른 firewall HTTP 응답.

판정 용어집

pending_approval을 포함한 모든 firewall 판정.

Firewall API

전체 콘솔 + 게이트웨이 라우트 레퍼런스.
보류가 더 넓은 제어 모델에 어떻게 들어맞는지는 강제 모드와 위험한 툴 호출을 참조하세요.