Chuyển đến nội dung chính
Khi một quy tắc firewall trả về pending_approval, cuộc gọi tool được giữ và agent của bạn chờ. Theo mặc định một người duyệt xóa lần giữ đó từ console. Webhook phê duyệt firewall nối cùng cổng đó vào hệ thống của bạn: gateway POST một thông báo có chữ ký tới endpoint của bạn ngay khi một cuộc gọi được giữ, và hệ thống của bạn POST một quyết định ký HMAC trở lại để giải phóng nó — không chỗ ngồi console, không poll một con người. Đây là nửa async (callback) của con-người-trong-vòng-lặp. Cuộc gọi được giữ, verdict, và đường phân giải console được đề cập trong Phân giải phê duyệt và tham chiếu Firewall; trang này chỉ là việc nối dây webhook.
Webhook là một báo trước đường-nhanh, không phải hệ thống ghi chép. Long- poll của relay trên cuộc gọi được giữ là cổng có thẩm quyền — nếu một thông báo bị rớt hoặc bộ nhận của bạn down, lần giữ vẫn đứng và một người duyệt có thể xóa nó từ console. Cấu hình webhook chỉ thêm một cách lập trình để phân giải nó.

​
1. Khi nào dùng một webhook phê duyệt firewall

Dùng nó khi một cổng firewall con-người-trong-vòng-lặp phải được phân giải bởi một thứ khác con người nhấp một nút:

Định tuyến tới UI phê duyệt của riêng bạn

Đẩy các cuộc gọi tool được giữ vào Slack, PagerDuty, hoặc một hàng đợi xem xét nội bộ và phân giải chúng nơi team của bạn đã làm việc.

Chính sách lập trình

Tự-phê-duyệt một db.query được giữ trên một read replica, tự-từ-chối một cái trên prod — code của bạn quyết định, gateway thực thi.

​
2. Cấu hình nó trong console

Cả hai nửa sống trên một cài đặt workspace. Mở Firewall → Settings và điền hai trường (một hành động Developer+ — thao tác ghi cài đặt được giới hạn vai trò):
Endpoint https:// mà chúng tôi POST tới khi một cuộc gọi được giữ. HTTP bị từ chối, và URL được chạy qua một SSRF preflight khi lưu, nên một đích đến loopback, dải-riêng, hay cloud-metadata bị từ chối trước khi nó có thể được lưu. Để trống để vô hiệu hóa đường async hoàn toàn.
Một HMAC secret chỉ-ghi (tối đa 255 ký tự). Nó ký thông báo đi-ra của chúng tôi và xác thực callback đi-vào của bạn. Console không bao giờ echo nó trở lại — một khi lưu bạn chỉ thấy rằng một secret được đặt; xoay vòng bằng cách viết một giá trị mới.
Endpoint callback là chỉ-HMAC. Cho đến khi một shared secret được đặt, gateway sẽ không giao các thông báo và từ chối mọi callback — cổng chỉ có thể được xóa từ console. Đặt secret để bật đường async.
Thích REST API hơn? Cùng các trường cập nhật qua route cài đặt console (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. Thông báo chúng tôi gửi bạn

Khi một cuộc gọi được giữ, chúng tôi POST một phong bì JSON có chữ ký tới URL của bạn: 
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
  }
}
Phong bì là một tín hiệu định tuyến, không phải ngữ cảnh đầy đủ — nó mang approval_id bạn cần để phân giải và các định danh để tương quan, không bao giờ các đối số tool. Chi tiết đối số sống trong hàng đợi Approvals và events log của firewall.
Xác minh chữ ký đi-ra trước khi bạn tin payload: X-Orca-Signature là sha256= + hex HMAC-SHA256(secret, raw_body) trên chính các byte bạn nhận. So sánh trong thời gian hằng. Giao là ít-nhất-một-lần và retry khi lỗi tạm thời, nên hãy làm handler của bạn idempotent trên approval_id.

​
4. Callback bạn POST trở lại

Để giải phóng (hoặc từ chối) lần giữ, POST quyết định của bạn tới endpoint callback với approval_id từ thông báo: 
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 là approved hoặc rejected — không giá trị nào khác được chấp nhận. reason là tùy chọn và hiện ra trên audit trail của phê duyệt đã được phân giải.
Chữ ký callback được ràng buộc vào approval id, nên một chữ ký bị bắt không thể được replay lên một cuộc gọi được giữ khác. Ký chuỗi <approval_id> + một ký tự xuống dòng literal (\n) + thân request thô:
X-Orca-Signature = "sha256=" + HMAC_SHA256(secret, approval_id + "\n" + body)
Cái này khác với thông báo đi-ra, vốn ký chỉ thân. Một callback mà chữ ký không xác minh nhận 401 — và một approval id thiếu, không khớp, hoặc không tồn tại trả về cùng 401, nên endpoint không bao giờ xác nhận liệu một id có tồn tại.
Callback là first-decision-wins và idempotent: ai phân giải trước — webhook của bạn hoặc một người duyệt console — đặt kết cục, và một callback lặp lại cho một phê duyệt đã-phân-giải trả về 200 nên hệ thống của bạn ngừng retry.

​
5. Giải phóng cuộc gọi được giữ

Phân giải phê duyệt không replay cuộc gọi tool cho bạn — nó nâng cổng để agent của bạn có thể phát lại nó. Agent runtime:
  1. Poll trạng thái của lần giữ tại GET /api/v1/firewall/approvals/:id (một key phạm-vi-firewall-gateway, không phải relay key hay session console của bạn) cho đến khi nó rời pending.
  2. Khi approved, gửi lại cuộc gọi tool gốc mang một header X-OrcaRouter-Firewall-Approval dùng-một-lần — gateway cho cuộc gọi đó đi qua và token được tiêu.
Nếu quy tắc bên dưới được chỉnh sửa sau khi cuộc gọi được giữ, hàng đợi Approvals gắn cờ rằng quy tắc đã thay đổi kể từ đó và nén mệnh đề “held because…” giờ-đã-cũ, nên một người duyệt console không hành động trên xuất xứ không còn khớp cái đã giữ cuộc gọi.

​
6. Xác minh việc nối dây

Một kiểm tra đầu-cuối nhanh trước khi bạn phụ thuộc vào nó:
BướcLàm gìKỳ vọng
Giữ một cuộc gọiKích hoạt một quy tắc với một verdict pending_approval400 firewall_approval_pending
Thông báoQuan sát endpoint của bạnPOST firewall.approval.pending có chữ ký đến
CallbackPOST một { "decision": "approved" } có chữ ký200 với trạng thái đã phân giải
Chặn replayPOST callback lần nữa200, đã phân giải (không áp-dụng-kép)
Nếu thông báo không bao giờ đến, xác nhận secret được đặt (không có nó gateway sẽ không giao) và rằng URL đã qua các kiểm tra HTTPS + SSRF tại thời điểm lưu.

​
7. Cái này khớp vào đâu

Phân giải phê duyệt

Đường người duyệt console và toàn bộ vòng đời cuộc-gọi-được-giữ.

Verdict

Nơi pending_approval đến từ đâu và cách nó kết hợp với các verdict khác.

Gateway key

Tạo key phạm-vi-firewall-gateway mà luồng poll + gửi-lại cần.

Quyền tự quyết quá mức

Mối đe dọa mà các cổng con-người-trong-vòng-lặp được xây để kiềm chế.
Để biết mô hình verdict, các bề mặt thực thi, và phần còn lại của firewall, xem tham chiếu Firewall.