الملخص
تتيح Webhooks لتطبيق Safety إشعار نظام آخر في اللحظة التي يقع فيها حدث ما في حسابك: عند تقديم بلاغ عن حادثة، أو تغيّر تحقيق، أو اكتمال إجراء تصحيحي. تسجّل عنواناً قادراً على استقبال هذه الإشعارات، وتختار الأحداث التي ينبغي أن تصل إليه، ويمكنك إضافة مفتاح توقيع سري حتى يتأكد النظام المستقبِل من أن كل رسالة صادرة فعلاً عن تطبيق Safety. تتناول هذه المقالة إنشاء webhook وتأمينه ومراقبة عمليات التسليم وحذفه.
المقدمة
تعمل معظم برامج السلامة جنباً إلى جنب مع أدوات أخرى: مساحة محادثة يتواصل فيها الفريق أصلاً، وخدمة أتمتة تفتح التذاكر، ومستودع بيانات لإعداد التقارير، ولوحة معلومات تشغيلية. وبدون webhooks، تضطر تلك الأنظمة إلى سؤال تطبيق Safety باستمرار عمّا إذا كان أي شيء قد تغيّر. أما مع webhooks، فيُخبرها تطبيق Safety بنفسه فور وقوع كل حدث.
يتولى تهيئة webhooks مسؤولو النظام من فئة Super Admin ضمن إعدادات الحساب. وهي تعالج مشكلة التأخير والازدواجية بين الأنظمة: فبدلاً من أن يعيد أحدهم إدخال حادثة في أداة ثانية، أو أن تتأخر لوحة معلومات تُحدَّث وفق مؤقّت زمني عن الواقع، يُخطَر النظام المستقبِل لحظة وقوع الحدث ويستطيع التصرّف بناءً عليه فوراً.
المفاهيم الأساسية
- Webhook: اتصال محفوظ بين حسابك في تطبيق Safety وعنوان خارجي واحد، يغطي مجموعة مختارة من الأحداث. ولكل webhook اسمه وعنوانه ومجموعة أحداثه وسجل تسليمه الخاص.
- نقطة النهاية (Endpoint): العنوان الموجود على خادم تتحكم به أنت ويستقبل الإشعارات. ويجب أن يكون قابلاً للوصول عبر اتصال آمن وقادراً على قبول الطلبات الواردة.
- الحدث (Event): الأمر المحدد الذي يقع في تطبيق Safety، مثل تقديم بلاغ عن حادثة أو وضع علامة اكتمال على إجراء تصحيحي، والذي يؤدي إلى إطلاق webhook.
- مفتاح التوقيع السري (Secret): قيمة اختيارية تضبطها على webhook. يستخدمها تطبيق Safety لتوقيع كل رسالة يرسلها، بحيث يستطيع النظام المستقبِل التأكد من أن الرسالة أصلية ولم تُعدَّل في الطريق.
- سجل التسليم: سجل محاولات الإرسال الأخيرة الخاصة بـ webhook واحد، ويُظهر الحدث، وما إذا نجحت المحاولة، والاستجابة التي أعادتها نقطة النهاية لديك، وأي رسالة خطأ، ووقت المحاولة.
- حالات الإخفاق (Failures): عدد عمليات التسليم الأخيرة التي لم تنجح، ويظهر في قائمة webhooks حتى يتبيّن أي اتصال معطّل دون الحاجة إلى فتح السجل.
الخطوات التي يجب اتباعها
فتح إعدادات Webhooks
سجّل الدخول بصفتك Super Admin، ثم افتح الإعدادات (Settings)، ثم مجموعة التكاملات (Integrations)، ثم Webhooks. تعرض الصفحة كل webhook مُهيّأ في حسابك. وإلى جانب كل واحد منها يمكنك أن ترى ما إذا كان نشطاً (Active)، وكم عدد حالات الإخفاق (Failures) الأخيرة المسجّلة له، ومتى كان آخر إطلاق (Last Triggered)، وهي معاً تمنحك قراءة سريعة لسلامة كل اتصال.
تجهيز نقطة نهاية لاستقبال الإشعارات
قبل إنشاء webhook، تأكّد من أن لديك عنواناً يقبل الطلبات الواردة عبر اتصال آمن، وأنك تتحكم به. وينبغي أن يُقرّ النظام المستقبِل باستلام كل رسالة سريعاً: فإذا ردّت نقطة النهاية لديك بخطأ أو استغرقت وقتاً طويلاً في الرد، تُسجَّل المحاولة على أنها تسليم فاشل لا ناجح. ومن المفيد التأكد من عمل نقطة النهاية قبل توجيه تطبيق Safety إليها، حتى يسهل تفسير أي إخفاقات مبكرة.
إنشاء webhook
اختر + New Webhook واملأ النموذج:
- الاسم (Name) يعرّف الاتصال داخل القائمة. استخدم اسماً يوضّح إلى أين تذهب الرسائل ولماذا، حتى يفهم زميل يراجع القائمة لاحقاً الغرض منه.
- العنوان (URL) هو العنوان الآمن الكامل لنقطة النهاية لديك.
- الأحداث (Events) تحدد التغييرات التي تُطلق رسالة. ويمكنك إرسال عدة أحداث إلى نقطة نهاية واحدة، أو إنشاء webhook منفصل لكل حدث إذا كنت تفضّل إبقاء كل مسار مستقلاً.
- مفتاح التوقيع السري (Secret (for HMAC signing)) اختياري لكن يُنصح به بشدة، وهو موضّح أدناه.
اختر Create. يصبح webhook نشطاً على الفور ويرسل عند أول حدث مطابق.
تعليق: اختر + New Webhook واملأ النموذج.
اختيار الأحداث التي تُرسَل
يستطيع تطبيق Safety إشعار نقطة النهاية لديك عند تقديم بلاغ جديد عن حادثة، وعند تعديل حادثة، وعند انتقال حادثة إلى حالة جديدة. أما على مستوى التحقيقات، فيمكنه إشعارك عند فتح تحقيق جديد وعند تعديل تحقيق قائم. وبالنسبة للإجراءات التصحيحية والوقائية، يمكنه إرسال رسالة عند إنشاء إجراء، وعند تحديثه، وعند وضع علامة اكتمال عليه. كما يمكنه إشعارك عند تسجيل قرار مراجعة امتثال، وعند إنشاء تكليف تدريبي لمستخدم.
اختر فقط الأحداث التي سيتصرف النظام المستقبِل بناءً عليها فعلاً. فـ webhook المشترك في كل شيء يولّد حركة بيانات يتعيّن على الطرف الآخر تصفيتها، ويجعل قراءة سجل التسليم أصعب عند تتبّع الأعطال.
تعليق: يستطيع تطبيق Safety إشعار نقطة النهاية لديك عند تقديم بلاغ جديد عن حادثة، وعند تعديل حادثة، وعند انتقال حادثة إلى حالة جديدة.
تأمين عمليات التسليم بمفتاح توقيع سري
عند إدخال قيمة في حقل Secret (for HMAC signing)، يوقّع تطبيق Safety كل طلب يرسله إلى تلك النقطة، ويرسل التوقيع مرفقاً بالرسالة. عندها يستطيع نظامك المستقبِل إعادة احتساب التوقيع من المفتاح السري نفسه ومقارنة القيمتين قبل التصرّف بأي شيء.
ولهذا أهمية بالغة، لأن نقطة نهاية تقبل رسائل غير موقّعة ستتصرّف بناءً على أي شيء يُرسَل إلى عنوانها من أي جهة تكتشفه. والتحقق من التوقيع هو الفارق بين نقطة نهاية تثق بتطبيق Safety وأخرى تثق بكل من يرسل إليها. شارك المفتاح السري مع النظام الذي يحتاجه فقط، وتعامل معه بالعناية نفسها التي تتعامل بها مع كلمة المرور.
مراجعة سجلات التسليم وإدارة webhooks
للتحقق من أن webhook يعمل، اختر أيقونة السجل في صفّه. يُفتح سجل التسليم ويعرض المحاولات الأخيرة مع الحدث، والنتيجة، والاستجابة التي أعادتها نقطة النهاية لديك، وأي رسالة خطأ، والطابع الزمني. وهذا أول مكان ينبغي النظر فيه عندما يتوقف نظام تابع عن الاستجابة، لأنه يخبرك بما إذا كان تطبيق Safety قد أرسل الرسالة وبما ردّت به نقطة النهاية لديك.
كما يوفّر كل صف أيقونة تحرير لتغيير الاسم أو العنوان أو الأحداث أو المفتاح السري، وأيقونة حذف تزيل webhook نهائياً وتوقف كل عمليات التسليم اللاحقة إلى تلك النقطة.
الخاتمة
يحوّل webhook تغييراً يقع في تطبيق Safety إلى رسالة فورية تصل إلى نظام يحتاج إلى معرفته. امنح كل اتصال اسماً واضحاً، واشترك به فقط في الأحداث التي يتصرّف بناءً عليها الطرف المستقبِل، واضبط دائماً مفتاح توقيع سري حتى يتمكن الطرف الآخر من التحقق مما يصله، واستخدم سجل التسليم كأول أداة تشخيص عندما يصمت نظام تابع. وبهذه التهيئة، تبقي webhooks الأنظمة المحيطة ببرنامج السلامة لديك محدَّثة دون أن ينسخ أحد البيانات بينها.