Webhooks في إدارة المشاريع: أتمتة بين الأنظمة دون استعلام متكرر
المهمة المجدولة التي تسأل كل ساعة «هل من جديد؟» تتأخر حين يهم التوقيت وتعمل حين لا يوجد شيء. هذا الدليل لمسؤولي تقنية المعلومات وفرق التكامل: متى تستخدم Webhooks، وكيف تبني مستقبلًا يتحمل الفشل.
استخدم Webhooks في إدارة المشاريع حين يحتاج نظام آخر أن يتصرف فور وقوع حدث محدد في نظام المشاريع، مثل اعتماد مشروع أو قبول مخرج أو اعتماد ساعات، وحين يستطيع ذلك النظام استقبال طلب على عنوان يُتاح له. وأبقِ الاستعلام الدوري أو الملفات المجدولة للمزامنة الكاملة والكميات الكبيرة والأنظمة التي لا تستقبل طلبات. أما الفشل فيُعالج بالتصميم لا بالأمل: تحقق من توقيع كل حدث، واقبله بسرعة ثم عالجه لاحقًا، وتجاهل المكرر بمعرّفه، ولا تعتمد على ترتيب الوصول، وراقب الإخفاقات، وأضف مطابقة دورية تلتقط ما فات.
أول تكامل يُبنى بين نظام المشاريع والأنظمة الأخرى يكون غالبًا مهمة مجدولة تسأل كل ساعة: «هل من جديد؟». تعمل المهمة، لكنها تتأخر حين يحتاج الناس السرعة، وتستهلك الموارد حين لا يوجد جديد. الـ Webhooks تقلب الاتجاه: النظام يخبر الآخرين حين يقع الحدث. هذا الدليل لمسؤولي تقنية المعلومات وفرق التكامل: متى يكون هذا الاتجاه صحيحًا، وكيف يُبنى المستقبل بحيث لا يضيع حدث ولا يُعالج مرتين.
ما الحدث، وكيف يختلف Webhook عن الاستعلام الدوري؟
الحدث تغيير له معنى في العمل: مشروع اعتُمد، ومخرج قُبل، وجدول ساعات اعتُمد، ومهمة تأخرت. في الاستعلام الدوري يسأل النظام المستقبل نظام المشاريع على فترات عن التغييرات، فيعرف بالحدث متأخرًا بمقدار الفترة، ويسأل حتى حين لا يوجد شيء. وفي Webhook يرسل نظام المشاريع طلبًا إلى عنوان يحدده النظام المستقبل لحظة وقوع الحدث، فيتفاعل فورًا.
النظام يوفر الاتجاهين: واجهة REST بصيغة JSON للقراءة والإنشاء والتحديث وفق الصلاحيات، وWebhooks تُرسل إلى عنوان تحدده عند وقوع حدث، كما في صفحة واجهة API وWebhooks. والتكامل الجيد يستخدمهما معًا كما سيتضح.
- وقوع الحدثاعتماد، أو قبول، أو تأخر، في نظام المشاريعنظام المشاريع
- التوقيع والإرسالطلب موقع إلى العنوان المسجل، وإعادة محاولة عند الفشلنظام المشاريع
- التحقق والقبولفحص التوقيع والمعرّف، وحفظ الحدث، ورد سريع بالنجاحالمستقبل
- المعالجةقراءة الحالة الحالية عبر API ثم تنفيذ الإجراء مرة واحدةالمستقبل
- المطابقة الدوريةمقارنة الطرفين لالتقاط ما فاتفريق التكامل
متى تختار Webhooks ومتى يبقى الاستعلام أصح؟
القرار لا يحسمه تفضيل تقني، بل أربعة أسئلة عن الحالة نفسها: كم يهم التوقيت؟ وكم عدد الأحداث؟ وهل يستطيع المستقبل استقبال طلب من الخارج؟ وهل تحتاج نسخة كاملة من البيانات أم إشعارًا بتغيير؟
| الحالة | Webhook | استعلام دوري عبر API | ملف مجدول |
|---|---|---|---|
| إجراء فوري بعد حدث محدد (فتح مركز تكلفة بعد اعتماد مشروع) | ✓ | جزئي، بتأخير الفترة | ✗ |
| تنبيه عاجل في قناة الفريق عند تأخر مهمة | ✓ | ✗ | ✗ |
| مزامنة كاملة لبيانات كثيرة يوميًا لأداة تحليل | ✗ | ✓ | ✓ |
| نظام قديم لا يستقبل طلبات ولا يوفر واجهات | ✗ | ✗ | ✓ |
| مستقبل داخل شبكة مغلقة لا يُتاح له عنوان | جزئي، إن كان المرسل داخل الشبكة نفسها | ✓ | ✓ |
| مطابقة دورية للتأكد من أن الطرفين متطابقان | ✗ | ✓ | جزئي |
لاحظ الصف الخامس: في التشغيل على سيرفرات المنشأة يتم التكامل مباشرة داخل الشبكة دون فتح منافذ للخارج، كما في صفحة التشغيل على سيرفرات المنشأة، فيصبح الـ Webhook إلى نظام داخلي أبسط أمنيًا. أما في التشغيل السحابي فالمستقبل يحتاج عنوانًا يصل إليه المرسل، وهذا قرار يشارك فيه فريق الأمن. ولأنواع الربط الأخرى وطرق تقييمها، راجع دليل المشتري لواجهة API في نظام إدارة المشاريع.
أمثلة Webhooks في إدارة المشاريع وما يتحقق منه المستقبل
صفحة الواجهة البرمجية تذكر ستة أحداث أمثلةً لما يرسله النظام. لكل منها استخدام شائع، ولكل استخدام سؤال يجب أن يجيب عنه المستقبل قبل التنفيذ:
| الحدث | استخدام شائع | ما يتحقق منه المستقبل قبل التنفيذ |
|---|---|---|
| project.approved | فتح مركز تكلفة في ERP | ألا يكون مركز التكلفة مفتوحًا مسبقًا لهذا المشروع |
| deliverable.accepted | إصدار فاتورة الدفعة | أن المخرج ما زال مقبولًا لحظة الإصدار، وأن الفاتورة لم تصدر من قبل |
| timesheet.approved | ترحيل الساعات للرواتب | أن الجدول لم يُرحّل سابقًا، وأن الفترة لم تُقفل في نظام الرواتب |
| task.overdue | تنبيه في قناة Teams | أن المهمة ما زالت متأخرة، وأن التنبيه لم يُرسل للمهمة نفسها قريبًا |
| budget.threshold | تنبيه للمالية | الحد الذي تجاوزه المشروع وقيمة الميزانية الحالية لا قيمة لحظة الإرسال |
| user.deactivated | مزامنة أنظمة الوصول | أن الحساب ما زال معطلًا، لأن إعادة التفعيل قد تصل بعده |
وإن احتجت إشعارًا لنظام خارجي عند حدث آخر، فقواعد الأتمتة في النظام تتيح أن يكون إجراء القاعدة إرسال Webhook أو استدعاء API لنظام خارجي، بعد اختيار الحدث والشرط من القوائم، مع وضع محاكاة لاختبار القاعدة قبل تفعيلها وسجل لكل تنفيذ. هنا يظهر الفصل بين المستويات: إرسال الحدث وقواعد الأتمتة ميزة تعمل بالإعداد؛ وبناء المستقبل في النظام الآخر تكامل يبنيه فريقكم بالتوثيق وبيئة الاختبار أو يتولاه فريق التنفيذ؛ ومطابقة الحقول واتجاه البيانات تهيئة تُوثق أثناء التنفيذ؛ وأي حدث لا تغطيه الأمثلة ولا قواعد الأتمتة متطلب يُبحث في التحليل ويُقدّر قبل الالتزام به.
التوقيع والتحقق: كيف يثق المستقبل بالحدث؟
عنوان الـ Webhook عنوان يستقبل طلبات. إن لم يتحقق المستقبل من المرسل، يستطيع أي طرف يعرف العنوان أن يرسل «مخرجًا مقبولًا» مزيفًا فتصدر فاتورة. لذلك تُوقّع أحداث النظام للتحقق من أنها صادرة منه فعلًا، كما تذكر صفحة الواجهة البرمجية.
الأسلوب الشائع في التوقيع هو رمز مصادقة الرسائل المبني على دالة تجزئة بمفتاح سري (HMAC) الموصوف في المعيار RFC 2104: يحسب المرسل قيمة من محتوى الطلب والمفتاح السري المشترك، ويعيد المستقبل الحساب ويقارن. وما يطلبه فريقكم من المورد كتابيًا، لأنه يحدد طريقة بناء المستقبل:
- خوارزمية التوقيع وموضعه: أي دالة، وفي أي ترويسة يصل التوقيع، وعلى أي جزء من الطلب يُحسب.
- الطابع الزمني: هل يدخل وقت الإرسال في التوقيع؟ وجوده يسمح للمستقبل برفض حدث قديم أُعيد إرساله من طرف ثالث.
- تدوير المفتاح: كيف يُغيَّر المفتاح السري دون توقف، وهل تُقبل فترة انتقالية بمفتاحين.
- عناوين المرسل: هل تصدر الأحداث من عناوين ثابتة يمكن للمستقبل تقييدها، أم يُعتمد على التوقيع وحده.
ممارسة جيدة في المستقبل: عامل محتوى الحدث إشعارًا لا مصدرًا نهائيًا للحقيقة. استلم المعرّف ونوع الحدث، ثم اقرأ الحالة الحالية للسجل عبر API برمز وصول مقيد. الواجهة تعمل عبر OAuth 2.0 أو رموز وصول مخصصة للتكاملات بنطاقات صلاحيات محددة لكل رمز، ويمكن تقييد عناوين IP المسموح لها بالطلب، ويُسجل كل طلب في سجل التدقيق. هذا يحمي من الحدث المزيف ومن الحدث القديم معًا.
إعادة المحاولة: ماذا يحدث حين يتعطل المستقبل؟
المستقبل سيتعطل يومًا: نافذة صيانة في نظام الرواتب، أو خادم مثقل، أو شهادة منتهية. السؤال ليس «هل سيفشل التسليم؟» بل «ماذا يحدث بعده؟». في صفحة التكاملات أن كل عملية تكامل مسجلة بوقتها ونتيجتها، وأن المحاولة تُعاد تلقائيًا عند الفشل، ويُنبَّه المسؤول عند تكرار الفشل، مع إمكانية إعادة التنفيذ يدويًا. تفاصيل هذه السياسة للـ Webhooks تحديدًا هي ما تسأل عنه:
- عدد المحاولات والفواصل بينها: هل تتباعد المحاولات تدريجيًا، وما آخر محاولة؟
- معيار النجاح: أي رد يعتبره المرسل نجاحًا؟ عادة فئة الرموز 2xx التي تعني في معيار دلالات HTTP (RFC 9110) أن الطلب استُلم وفُهم وقُبل.
- مهلة الانتظار: كم ينتظر المرسل الرد قبل اعتبار المحاولة فاشلة؟ مستقبل بطيء يتجاوز المهلة سيستلم الحدث نفسه مرة أخرى.
- مدة الاحتفاظ بالحدث الفاشل: وهل يمكن إعادة إرساله من سجل التكامل بعد إصلاح المستقبل؟
ومن جهة المستقبل قاعدتان تمنعان أغلب المشكلات: رُد بالنجاح بعد حفظ الحدث لا بعد معالجته، فالمعالجة الطويلة داخل الطلب تتجاوز المهلة وتولّد تكرارًا؛ ولا ترد بالنجاح على حدث لم يُحفظ، لأن الرد بالنجاح يوقف إعادة المحاولة ويضيع الحدث.
التكرار والترتيب: صمم على أن الحدث قد يصل مرتين
إعادة المحاولة تعني حتمًا أن حدثًا ما سيصل أكثر من مرة: المستقبل عالجه لكن رده ضاع في الشبكة، فأعاد المرسل. وطلبات POST التي تحمل الأحداث عادة ليست «متساوية الأثر» بتعريف RFC 9110، أي أن تكرارها لا يضمن الأثر نفسه، لذلك تقع مسؤولية منع الأثر المزدوج على المستقبل:
- معرّف الحدث: احفظ معرّف كل حدث عالجته، وتجاهل أي حدث بمعرّف معالج سابقًا. واسأل المورد: هل لكل حدث معرّف ثابت بين المحاولات؟
- قيد في الهدف: حتى مع المعرّف، اجعل الإجراء نفسه يرفض التكرار: لا مركز تكلفة ثانيًا لرمز المشروع نفسه، ولا ترحيل ثانيًا لجدول الساعات نفسه.
والترتيب مشكلة أخرى: الأحداث قد تصل بغير ترتيب وقوعها، خاصة بعد إعادة المحاولة. قد يصل تعطيل مستخدم بعد إعادة تفعيله، أو تنبيه تجاوز ميزانية قبل أن يُعالج اعتماد المشروع نفسه. الحل ليس انتظار الترتيب، بل ثلاثة أنماط:
- اقرأ الحالة الحالية: عند كل حدث، اسأل الواجهة عن حالة السجل الآن، وتصرف بناءً عليها لا على محتوى الحدث.
- قارن الوقت أو الإصدار: إن حمل الحدث وقت وقوعه، فلا تُطبق حدثًا أقدم من آخر حالة طبقتها للسجل نفسه.
- أجّل ما ينقصه أصله: حدث يخص مشروعًا لم يُعرف بعد يُحفظ ويُعاد فحصه، ولا يُرفض نهائيًا.
المراقبة: التكامل الذي يفشل بصمت أخطر من غيابه
أسوأ ما في الـ Webhooks أن فشلها لا يراه المستخدم. مدير المشروع يرى المشروع معتمدًا، والمالية لا ترى مركز تكلفة، ولا أحد يعرف لماذا حتى يُسأل عن أمر شراء لا يجد مركزًا. لذلك تُراقب أربعة أشياء، ولكل منها مالك:
| المؤشر | ما يكشفه | المالك |
|---|---|---|
| الإخفاقات المتكررة في سجل التكامل | مستقبل متعطل أو شهادة منتهية أو مفتاح توقيع مختلف | فريق التكامل، بتنبيه من النظام عند التكرار |
| الأحداث المحفوظة غير المعالجة لدى المستقبل | معالجة متوقفة رغم نجاح الاستلام | فريق النظام المستقبل |
| الأحداث المرفوضة بتوقيع غير صحيح | محاولة تزوير أو مفتاح غير محدث بعد التدوير | الأمن وفريق التكامل |
| فروق المطابقة الدورية | أحداث فاتت رغم كل ما سبق | مالك البيانات في كل طرف |
المطابقة الدورية هي الطبقة التي تمنح الثقة: مهمة يومية تقرأ عبر الواجهة المشاريع المعتمدة وتقارنها بمراكز التكلفة المفتوحة، أو الجداول المعتمدة بما رُحّل للرواتب. الـ Webhook يعطي السرعة، والمطابقة تعطي الاكتمال. وطلبات الواجهة نفسها تُسجل في سجل التدقيق بالتكامل والوقت والعملية، فيمكن تتبع ما قرأه كل تكامل وما عدّله.
قائمة تحقق لمستقبل Webhook مقاوم للأخطاء
هذه القائمة تُسلَّم لمن يبني المستقبل، سواء كان فريقكم أو فريق التنفيذ، وتُراجع قبل ربطه بالإنتاج:
- العنوان يعمل عبر HTTPS فقط، ولا يقبل طلبًا بلا توقيع صحيح.
- التحقق من الطابع الزمني إن وُجد، ورفض الأحداث الأقدم من حد متفق عليه.
- حفظ الحدث في طابور أو جدول قبل الرد، ثم الرد بالنجاح فورًا.
- المعالجة في عملية منفصلة عن الاستلام، مع إعادة محاولة داخلية لأخطائها.
- سجل بمعرّفات الأحداث المعالجة، وتجاهل المكرر.
- قيد يمنع الأثر المزدوج في النظام الهدف نفسه.
- قراءة الحالة الحالية عبر API قبل أي إجراء له أثر مالي أو صلاحيات.
- مكان للأحداث التي فشلت معالجتها نهائيًا، مع تنبيه ومراجعة يدوية.
- مفتاح التوقيع ورموز الوصول في مخزن أسرار، مع إجراء تدوير موثق.
- مهمة مطابقة دورية، ومالك لفروقها.
سيناريو: ترحيل الساعات المعتمدة إلى الرواتب
شركة استشارات هندسية افتراضية بنحو 220 موظفًا يسجلون ساعاتهم أسبوعيًا على المشاريع، وتحتسب بعض البدلات من الساعات المعتمدة. كان الترحيل ملفًا يُصدَّر يدويًا آخر الشهر، فتصل الساعات المعتمدة متأخرًا وتُكتشف الأخطاء بعد إقفال الرواتب. قررت الشركة ربط الحدث timesheet.approved بخدمة استقبال لدى فريق الرواتب.
بُني المستقبل على القائمة السابقة، ثم اختُبر في بيئة الاختبار المنفصلة قبل الإنتاج. وظهرت قيمة التصميم في الشهر الثاني: توقف نظام الرواتب في نافذة صيانة لساعات، فأعاد النظام المحاولة ونبّه المسؤول عند تكرار الفشل، ثم وصلت الأحداث بعد عودة النظام. وصل عدد منها مرتين لأن ردود بعض المحاولات ضاعت، فتجاهلها المستقبل بمعرّفاتها، ورفض نظام الرواتب ترحيلًا ثانيًا لجدول مرحّل. وفي آخر الشهر أظهرت المطابقة جدولين اعتُمدا ثم أعيد فتحهما وعدّلا، فعولجا يدويًا قبل الإقفال.
ما تغير ليس السرعة وحدها، بل أن الفشل صار مرئيًا ومحدودًا. أما تفاصيل البيانات المتبادلة مع الموارد البشرية نفسها (الموظفون والهيكل والإجازات وتكلفة الساعة) فموضوع دليل تكامل نظام المشاريع مع الموارد البشرية، وأنماط الربط مع المالية في دليل ربط نظام إدارة المشاريع مع ERP.
اختبارات قبل ربط المستقبل بالإنتاج
نفذ هذه الاختبارات في بيئة الاختبار، ووثق نتيجة كل منها في محضر قبول التكامل:
- حدث صحيح: يُعالج مرة واحدة، ويظهر أثره في النظام الهدف وفي سجل التكامل.
- توقيع خاطئ: يُرفض الحدث ولا يُعالج، ويُسجل الرفض.
- الحدث نفسه مرتين: الأثر يقع مرة واحدة.
- حدثان بترتيب معكوس: الحالة النهائية في الهدف تطابق الحالة الحالية في نظام المشاريع.
- مستقبل متوقف: أوقف المستقبل، وأطلق أحداثًا، ثم أعده؛ تأكد من إعادة المحاولة والتنبيه ووصول الأحداث.
- مستقبل بطيء: أبطئ الرد عمدًا وتأكد أن الاستلام يرد قبل المهلة وأن المعالجة تتم لاحقًا.
- تدوير المفتاح: غيّر مفتاح التوقيع وتأكد من عدم ضياع أحداث أثناء الانتقال.
- المطابقة: احذف أثر حدث يدويًا في الهدف، وتأكد أن المطابقة الدورية تكشفه.
الأسئلة الشائعة
لا. الـ Webhook يخبر بأن شيئًا حدث، والواجهة تُستخدم لقراءة الحالة الكاملة والتحقق منها ولتنفيذ المطابقة الدورية. التصميم الموثوق يستخدم الاثنين: الحدث للسرعة، والواجهة للدقة والاكتمال.
في التشغيل السحابي يحتاج المستقبل عنوانًا يصل إليه المرسل، ويُحمى بالتوقيع وHTTPS وبتقييد العناوين إن كانت عناوين المرسل ثابتة. وفي التشغيل على سيرفرات المنشأة يتم الربط داخل الشبكة دون فتح منافذ خارجية، فيكون المستقبل نظامًا داخليًا.
أي الطرفين، بحسب الاتفاق. يستطيع فريقكم التقني بناءه بالتوثيق وبيئة الاختبار المنفصلة، أو يتولاه فريق التنفيذ ضمن المشروع بالتنسيق مع فريق النظام الآخر. المهم أن تُسلَّم قائمة التحقق ومحضر الاختبارات مع التكامل أيًا كان منفذه.
اسأل المورد كيف تُرسل الأحداث عند العمليات الجماعية مثل الاستيراد أو إغلاق مجموعة مهام، وصمم المستقبل ليحفظ الأحداث في طابور ويعالجها بمعدل يتحمله النظام الهدف. وللمزامنة الكبيرة المتوقعة، استخدم الواجهة أو الملفات المجدولة بدل الأحداث الفردية.
الإشعار موجه لشخص يقرؤه، والـ Webhook موجه لنظام يتصرف. قد ينتهي الـ Webhook بتنبيه في قناة Teams كما في مثال task.overdue، لكن قيمته الأساسية في الإجراءات الآلية بين الأنظمة. وما يُرسل إلى Teams وOutlook من النظام مباشرة موضوع دليل ربط النظام مع Microsoft Teams وOutlook.
الخلاصة: السرعة من الحدث والثقة من التصميم
الـ Webhooks تجعل الأنظمة تتفاعل مع أحداث المشاريع لحظة وقوعها، لكنها لا تضمن الاكتمال وحدها. اختر الحدث حيث يهم التوقيت، وتحقق من التوقيع، واقبل بسرعة وعالج لاحقًا، وتجاهل المكرر، واقرأ الحالة الحالية بدل الاعتماد على الترتيب، وراقب الفشل، وأضف مطابقة دورية. بهذا يصبح التكامل شيئًا يمكن الوثوق به عند التدقيق.
وإن كنتم تخططون لربط نظام إدارة المهام والمشاريع بأنظمتكم، فالجلسة التقنية مع فريقنا مناسبة لمراجعة التوثيق وبيئة الاختبار، وطرح أسئلة التوقيع وإعادة المحاولة على تكاملكم المحدد.