مستمع ويب هوك Microsoft Graph

فكّر في الأمر بهذه الطريقة: بدلاً من أن يفحص هاتفك الثلاجة باستمرار ليرى إن كان الحليب قد نفد، ترسل لك الثلاجة رسالة نصية في اللحظة التي ينفد فيها الحليب. هذا بالضبط ما يفعله مستمع الويب هوك — ينتظر إشارة، ثم يتفاعل تلقائيًا.

---

ما الذي يفعله هذا فعليًا؟

مستمع ويب هوك Microsoft Graph هو ميزة في Hermes Agent تتيح لمايكروسوفت 365 (M365) إخبار Hermes عند حدوث شيء ما — مثل انتهاء اجتماع Teams، أو وصول رسالة دردشة جديدة، أو تحديث حدث في التقويم.

إنه ليس روبوت محادثة تتحدث معه. إنه أقرب إلى مساعد صامت يستمع إلى “إشعارات التغيير” من Microsoft Graph، ثم يشغّل خط أنابيب (Pipeline) للقيام بشيء مفيد — مثل جلب محضر اجتماع ونشر ملخصه مرة أخرى في Teams.

---

ما الذي تحتاجه قبل البدء

ستحتاج إلى ثلاثة أشياء:

1. بيانات اعتماد تطبيق Microsoft Graph — سجّل تطبيقًا في بوابة Azure من مايكروسوفت.
2. عنوان URL عام عبر HTTPS — لن يستدعي Microsoft Graph عنوان localhost. يعمل نفق التطوير (Dev Tunnel) للاختبار؛ أما النطاق الحقيقي فهو الأفضل للإنتاج.
3. سر قوي — هذه هي قيمة clientState الخاصة بك، وتُستخدم للتحقق من أن الإشعارات صادرة فعلاً من مايكروسوفت.

ولّد سرًا باستخدام:

openssl rand -hex 32

ضعه في ~/.hermes/.env هكذا:

MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here

---

إعداد البدء السريع

أبسط طريقة لتفعيل المستمع هي عبر ملف إعدادات بسيط (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-with-a-strong-secret"
      accepted_resources:
        - "communications/onlineMeetings"

أو استخدم متغيرات البيئة في ~/.hermes/.env (يتم دمجها تلقائيًا عند بدء التشغيل):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=your-generated-secret-here
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

ملاحظة: عنوان الربط (Bind Host) يُقرأ فقط من extra.host في ملف الإعدادات — لا يوجد متغير بيئة MSGRAPH_WEBHOOK_HOST لتجاوزه.

---

بدء تشغيل المستمع

شغّل هذا الأمر لبدء البوابة:

hermes gateway run

بمجرد التشغيل، يعرض المستمع هذه النقاط الطرفية (Endpoints):

• POST /msgraph/webhook — يستقبل إشعارات التغيير من Microsoft Graph
• GET /msgraph/webhook?validationToken=... — يعالج مصافحة التحقق من الاشتراك
• GET /health — فحص جاهزية مع عدّادات للإشعارات المقبولة/المكررة

---

جعله عامًا

لكي يتمكن Microsoft Graph من الوصول إلى المستمع الخاص بك، تحتاج إلى كشفه للعام. استخدم وكيلًا عكسيًا (Reverse Proxy)، أو نفق تطوير، أو بوابة دخول (Ingress). سيكون عنوان URL للإشعار الخاص باشتراكات Graph كما يلي:

https://ops.example.com/msgraph/webhook

---

ورقة مرجعية للإعدادات

جميع الإعدادات موجودة تحت platforms.msgraph_webhook.extra:

الإعداد	الافتراضي	وظيفته
host	غير محدد (جميع الواجهات)	عنوان الربط. استخدم 127.0.0.1 لأنفاق التطوير.
port	8646	المنفذ الذي يستمع عليه.
webhook_path	/msgraph/webhook	المسار الذي ترسل إليه Graph بيانات POST.
health_path	/health	نقطة فحص الجاهزية.
client_state	—	السر المشترك الخاص بك، يُقارن بشكل آمن.
accepted_resources	[] (يقبل الكل)	قائمة السماح لمسارات موارد Graph. استخدم * للبدل (Wildcards).

---

الملخص ونصيحة عملية

مستمع ويب هوك Microsoft Graph هو الجسر بين أحداث M365 وإجراءات Hermes. إنه ليس معقدًا — مجرد مستمع ينتظر إشارة، ثم يشغّل سير عمل.

نصيحة عملية: ابدأ بـ accepted_resources محدودًا بمورد واحد (مثل communications/onlineMeetings) للحفاظ على البساطة. بمجرد رؤية الإشعارات تتدفق، وسّع القائمة. واستخدم دائمًا client_state مولّدًا بشكل صحيح — فهو مصافحة الأمان الخاصة بك مع مايكروسوفت.

---