الانتقال إلى المحتوى الرئيسي
عندما تعيد قاعدة جدار حماية حكم pending_approval، تعلّق البوابة استدعاء الأداة وتُخطر نظام موافقاتك الخاص خارج النطاق. ذلك الإخطار هو POST مُوقَّع عبر HTTP — حمولة firewall webhook — وهذه الصفحة توثّق شكلها الدقيق حتى تستطيع التحقّق من التوقيع، وتوجيه الحدث، ونشر قرارك راجعاً. هذا الشقيق غير المتزامن لمسار الموافقة داخل وحدة التحكم الموصوف في صفحة جدار الحماية. مسار وحدة التحكم (يضغط مراجِع approve/reject) لا يحتاج webhook إطلاقاً. الـ webhook لأجل عندما تريد آلة — روبوت التذاكر الخاص بك، أو إجراء Slack، أو وقت تشغيل وكيل — أن تحلّ التعليق. كلا المسارين بمبدأ أول كاتب يفوز، فيمكنك تشغيلهما جنباً إلى جنب.
الـ webhook هو إشارة توجيه بأفضل جهد، وليس قناة HITL المرجعية. استطلاع الوكيل الطويل الخاص على GET /api/v1/firewall/approvals/:id هو الشبكة الاحتياطية — إذا سقط إخطار أو كانت نقطة نهايتك معطّلة لوهلة، لا يزال الاستدعاء المُعلَّق يظهر في وحدة التحكم ويُحَل بشكل طبيعي. الـ webhook يدع آلة تتفاعل أسرع مما يفعل إنسان فحسب.

​
1. حمولة firewall webhook في لمحة

ينشر OrcaRouter ظرف JSON إلى الـ URL الذي تضبطه، مُوقَّعاً بسرّ مشترك. ها هو تسليم كامل — ترويسات وجسم: 
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 حتى توجّه قبل تحليل الجسم.
المعرّف الصحيح لمساحة العمل التي علّقت سياستها الاستدعاء. مفيد عندما تتلقّى نقطة نهاية واحدة webhooks من عدة مساحات عمل.
طابع زمني RFC 3339 / UTC (دقة نانوثانية) لوقت إدراج البوابة للموافقة في الطابور. قابل للتحليل بأي أدوات أحداث قياسية.
الكتلة التي يحتاجها استدعاؤك الراجع لحل البوابة. الحقول في §3.

​
3. حمولة data

تحمل كتلة data كل ما يلزم لتوجيه التعليق وحلّه — بلا وسائط أداة عمداً. الـ webhook إشارة توجيه؛ وسياق الاستدعاء الكامل (الأداة، الوسائط، القاعدة التي أُطلقت) يعيش في تبويب Approvals بوحدة التحكم وسجلّ التدقيق، حيث يُتحكَّم في الوصول إليه.
الحقلالنوعالمعنى
approval_idstringالمعرّف الذي تنشر قرارك مقابله.
tool_namestringالأداة المُعلَّقة، مثل db.export.
request_idstringطلب الترحيل الذي أطلق التعليق.
conversation_idstringمعرّف محادثة / جلسة الوكيل.
policy_idintسياسة جدار الحماية التي طابقت.
rule_idintالقاعدة التي أعادت pending_approval.
تحتاج الوسائط أو العبارة المطابقة لاتخاذ القرار؟ اقرأها من تبويب Approvals بوحدة التحكم (Developer+)، أو اجعل وكيلك يستطلع GET /api/v1/firewall/approvals/:id برمز بوابته. الـ webhook لا يحمل الوسائط عبر السلك أبداً عن قصد.

​
4. التحقّق من التوقيع

كل تسليم مُوقَّع حتى ترفض التزييفات. ترويسة التوقيع هي: 
X-Orca-Signature: sha256=<hex HMAC-SHA256(secret, raw_body)>
حيث secret هو سرّ webhook الموافقة الذي تضبطه على مساحة العمل و 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)
توقيع الـ webhook الصادر يغطّي الجسم فقط. أما الاستدعاء الراجع الوارد الذي تنشره راجعاً (§6) فيوقّع approval_id + سطراً جديداً + الجسم — بناء مختلف، عن قصد، حتى لا يمكن إعادة تشغيل توقيع ملتقَط عبر الموافقات. لا تعِد استخدام روتين توقيع واحد للاتجاهين.

​
5. ضبط الـ webhook

الـ URL الوجهة والسرّ المشترك إعدادات مساحة عمل — اضبطهما مرة في وحدة التحكم (أو عبر واجهة الإعدادات؛ Developer+). لا تدخّل مشغّل ولا شيء لنشره.
1

اضبط الـ URL والسرّ

في إعدادات جدار الحماية، اضبط نقطة نهايتك HTTPS كـ URL لـ webhook الموافقة وسرّاً مشتركاً قوياً. يجب أن يكون الـ URL https:// — تُرفض الوجهات النصّية — والسرّ للكتابة فقط (لا يُعاد أبداً عند القراءة؛ تبلّغ استجابة الإعدادات فقط عمّا إذا كان واحد مضبوطاً).
2

ألّف قاعدة pending_approval

أضِف قاعدة جدار حماية حكمها pending_approval (أو استخدم الإعداد المسبق لـ HITL). انظر قواعد جدار الحماية.
3

استقبِل وتحقّق

تستقبل نقطة نهايتك POST المُوقَّع على الاستدعاء المُعلَّق التالي. تحقّق من التوقيع (§4)، ثم إمّا حُلّ عبر الاستدعاء الراجع أو أظهره لإنسان.
الاستدعاء المُعلَّق لا يزال يعمل مع عدم ضبط أي webhook — يظهر فقط في وحدة التحكم ليحلّه إنسان. وإذا ضبطت URL لكن بلا سرّ، تتخطّى البوابة الإرسال كلياً، لأن نقطة نهاية الاستدعاء الراجع لا تقبل سوى الطلبات المُوقَّعة: إخطار لا تستطيع مصادقته راجعاً سيكون عديم الفائدة.

​
6. الاستدعاء الراجع: حل التعليق

للموافقة أو الرفض بآلة، انشر راجعاً إلى: 
POST /api/v1/firewall/approvals/:id/callback
بنفس :id الذي تلقّيته كـ approval_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"
حقل الجسممطلوبالقيم
decisionنعمapproved أو rejected
reasonلاملاحظة نصّية حرّة، مُسجَّلة في سجلّ التدقيق.
قرار approved يدع محاولة الوكيل التالية تمرّ مرة واحدة — يعيد الوكيل تقديم الاستدعاء الأصلي بترويسة X-OrcaRouter-Firewall-Approval أحادية الاستخدام. قرار rejected يبقي الاستدعاء محجوباً.
الحل عديم الأثر التكراري وبمبدأ أول كاتب يفوز. إذا حلّ إنسان التعليق بالفعل من وحدة التحكم — أو وصل استدعاء راجع مكرّر — تعيد نقطة النهاية 200 بـ already_resolved: true ويبقى القرار الأصلي. آمن لإعادة المحاولة.

​
7. حالات الموافقة

يمرّ استدعاء مُعلَّق عبر هذه الحالات؛ يقود استدعاؤك الراجع الانتقال خارج pending:
الحالةالمعنى
pendingبانتظار قرار (الحالة وقت الـ webhook).
approvedمُحَلّ — قد يمضي الاستدعاء المبوَّب مرة واحدة.
rejectedمُحَلّ — يبقى الاستدعاء المبوَّب محجوباً.
expiredانتهت صلاحية التعليق دون قرار.

​
8. مراجع ذات صلة

جدار الحماية — مسار HITL

كيف يعلّق pending_approval استدعاءً ويعيد الوكيل التقديم بترويسة الموافقة أحادية الاستخدام.

رموز الأخطاء

firewall_approval_pending واستجابات HTTP الأخرى لجدار الحماية.

مسرد الأحكام

كل حكم لجدار الحماية، بما فيه pending_approval.

Firewall API

مرجع مسارات وحدة التحكم + البوابة الكامل.
لكيفية انسجام التعليقات مع نموذج التحكّم الأوسع، انظر أوضاع الفرض و استدعاءات الأدوات الخطرة.