الانتقال إلى المحتوى الرئيسي
عندما تعيد قاعدة جدار حماية pending_approval، يُعلَّق استدعاء الأداة وينتظر وكيلك. افتراضياً يمحو مراجِع ذلك التعليق من وحدة التحكم. webhook موافقة جدار الحماية يربط نفس البوابة بـ نظامك: ترسل البوابة POST بإشعار موقَّع إلى نقطة نهايتك لحظة تعليق استدعاء، ويرسل نظامك POST بقرار موقَّع بـ HMAC عائداً لتحريره — لا مقعد وحدة تحكم، لا استطلاع إنسان. هذا النصف اللامتزامن (الاستدعاء) من الإنسان في الحلقة. الاستدعاء المُعلَّق، والحكم، ومسار حل وحدة التحكم مغطّاة في حل الموافقات و مرجع جدار الحماية؛ هذه الصفحة هي مجرد ربط الـ webhook.
الـ webhook تنبيه مسار سريع، وليس نظام السجل. الاستطلاع الطويل للترحيل على الاستدعاء المُعلَّق هو البوابة الموثوقة — إذا أُسقِط إشعار أو كان مستقبِلك معطّلاً، يبقى التعليق قائماً ويمكن لمراجِع محوه من وحدة التحكم. ضبط الـ webhook يضيف فقط طريقة برمجية لحلّه.

​
1. متى تستخدم webhook موافقة جدار الحماية

الجأ إليه عندما يجب حل بوابة جدار حماية بالإنسان في الحلقة بشيء غير شخص ينقر زراً:

وجّه إلى واجهة موافقاتك الخاصة

ادفع استدعاءات الأدوات المُعلَّقة إلى Slack أو PagerDuty أو طابور مراجعة داخلي وحلّها حيث يعمل فريقك بالفعل.

سياسة برمجية

وافق تلقائياً على db.query مُعلَّق مقابل نسخة قراءة، ارفض تلقائياً واحداً مقابل prod — كودك يقرّر، البوابة تفرض.

​
2. اضبطه في وحدة التحكم

كلا النصفين يعيشان على إعداد مساحة عمل واحد. افتح Firewall → Settings واملأ حقلين (إجراء Developer+ — كتابة الإعدادات محكومة بالدور):
نقطة نهاية https:// التي نرسل POST إليها عند تعليق استدعاء. HTTP مرفوض، وتُمرَّر الـ URL عبر فحص SSRF مسبق عند الحفظ، فوجهة loopback أو نطاق خاص أو بيانات تعريف سحابة تُرفض قبل أن يمكن تخزينها. اتركه فارغاً لتعطيل المسار اللامتزامن بالكامل.
سر HMAC للكتابة فقط (حتى 255 حرفاً). يوقّع إشعارنا الصادر و يصادق استدعاءك الوارد. وحدة التحكم لا تردّده أبداً — بمجرد الحفظ ترى فقط أن سراً مضبوط؛ دوّر بكتابة قيمة جديدة.
نقطة نهاية الاستدعاء 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. الإشعار الذي نرسله لك

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

​
4. الاستدعاء الذي ترسله عائداً

لتحرير (أو رفض) التعليق، أرسل POST بقرارك إلى نقطة نهاية الاستدعاء بـ approval_id من الإشعار: 
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 اختياري ويظهر على مسار تدقيق الموافقة المحلولة.
توقيع الاستدعاء مرتبط بمعرّف الموافقة، فتوقيع ملتقَط لا يمكن إعادة تشغيله مقابل استدعاء مُعلَّق مختلف. وقّع السلسلة <approval_id> + سطر جديد حرفي (\n) + جسم الطلب الخام:
X-Orca-Signature = "sha256=" + HMAC_SHA256(secret, approval_id + "\n" + body)
هذا يختلف عن الإشعار الصادر، الذي يوقّع الجسم وحده. استدعاء توقيعه لا يُتحقَّق يحصل على 401 — ومعرّف موافقة غائب أو غير متطابق أو غير موجود يعيد نفس 401، فلا تؤكّد نقطة النهاية أبداً ما إذا كان معرّف موجوداً.
الاستدعاء أول-قرار-يفوز وعديم الأثر تكرارياً: أياً كان من يحل أولاً — webhook الخاص بك أو مراجِع وحدة تحكم — يضبط النتيجة، واستدعاء مكرَّر لموافقة محلولة بالفعل يعيد 200 فيتوقف نظامك عن إعادة المحاولة.

​
5. تحرير الاستدعاء المُعلَّق

حل الموافقة لا يعيد تشغيل استدعاء الأداة لك — يرفع البوابة فيمكن لوكيلك إعادة إصداره. زمن تشغيل الوكيل:
  1. يستطلع حالة التعليق على GET /api/v1/firewall/approvals/:id (مفتاح ضمن نطاق بوابة جدار الحماية، وليس مفتاح ترحيلك أو جلسة وحدة التحكم) حتى يغادر pending.
  2. عند approved، يعيد تقديم استدعاء الأداة الأصلي حاملاً ترويسة X-OrcaRouter-Firewall-Approval أحادية الاستخدام — تدع البوابة ذلك الاستدعاء الواحد يمر ويُستهلَك الرمز.
إذا حُرِّرت القاعدة الأساسية بعد تعليق الاستدعاء، يعلّم طابور الموافقات أن القاعدة تغيّرت منذ ذلك الحين ويكبت عبارة “عُلِّق لأن…” القديمة الآن، فلا يتصرّف مراجِع وحدة تحكم بناءً على أصل لم يعد يطابق ما علّق الاستدعاء.

​
6. تحقّق من الربط

فحص سريع من البداية إلى النهاية قبل أن تعتمد عليه:
الخطوةماذا تفعلالمتوقَّع
علّق استدعاءًأطلق قاعدة بحكم pending_approval400 firewall_approval_pending
الإشعارراقب نقطة نهايتكيصل POST موقَّع firewall.approval.pending
الاستدعاءأرسل POST موقَّعاً { "decision": "approved" }200 بالحالة المحلولة
حارس الإعادةأرسل الاستدعاء مجدداً200، محلولة بالفعل (لا تطبيق مزدوج)
إذا لم يصل الإشعار أبداً، أكّد أن السر مضبوط (بدونه لن تسلّم البوابة) وأن الـ URL اجتاز فحوصات HTTPS + SSRF وقت الحفظ.

​
7. أين يقع هذا

حل الموافقات

مسار مراجِع وحدة التحكم ودورة حياة الاستدعاء المُعلَّق الكاملة.

الأحكام

من أين يأتي pending_approval وكيف يتركّب مع الأحكام الأخرى.

مفاتيح البوابة

اسكك المفتاح ضمن نطاق بوابة جدار الحماية الذي يحتاجه تدفّق الاستطلاع + إعادة التقديم.

الوكالة المفرطة

التهديد الذي بُنيت بوابات الإنسان في الحلقة لاحتوائه.
لنموذج الحكم، وأسطح الفرض، وبقية جدار الحماية، انظر مرجع جدار الحماية.