Webhooks نظام الزوار رسائل لحظية يرسلها النظام إلى عنوان في أنظمتك عند وقوع حدث: اعتماد زيارة، أو وصول زائر، أو مغادرته، أو تجاوزه المدة، أو قرب انتهاء وثيقة مقاول. بها تؤتمت ما كان ينتظر مكالمة أو تقريرًا: إبلاغ غرفة الأمن بدخول منطقة حساسة، وفتح تذكرة للمرافق، وتحديث لوحة الموجودين، وإشعار فريق العمليات. نجاحها لا يتوقف على قائمة الأحداث وحدها، بل على المستقبِل الذي تبنيه: يتحقق من مصدر الحدث، ويرد بسرعة، ويعالج الحدث مرة واحدة ولو وصل مرتين، ويتحمل وصوله بغير ترتيبه. وأسماء الأحداث المتاحة ومحتواها تُؤكد دائمًا من وثائق المورد.
ما الذي تغيّره الأحداث اللحظية في التكامل؟
بدون أحداث، يعرف أي نظام آخر ما يجري في نظام الزوار بإحدى طريقتين: أن يسأل دوريًا («هل وصل الزائر؟») أو أن ينتظر تقريرًا مجدولًا. الأولى تستهلك الطلبات وتتأخر بمقدار الفاصل بين سؤالين، والثانية تصلح للتحليل لا للتصرف. الحدث يقلب الاتجاه: نظام الزوار يخبرك لحظة وقوع الشيء، فيتصرف نظامك فورًا.
صفحة REST API وWebhooks تصف ما يوفره النظام: واجهات REST بصيغة JSON، وأحداث لحظية، وإعادة إرسال الحدث عند فشل الاستلام مع سجل بمحاولات الإرسال، وبيئة اختبار، ومفاتيح منفصلة لكل نظام مرتبط بصلاحياته، وطبقة تكامل للأنظمة التي لا تتعامل مع REST أو الأحداث. وتذكر الصفحة أمثلة للأحداث، هي التي تبني عليها هذه المقالة:
| الحدث | متى يُرسل | نوع السؤال الذي يجيب عنه |
|---|---|---|
| visit.approved | اكتمال الموافقات | ما الذي يجب تجهيزه قبل وصول الزائر؟ |
| visitor.checked_in | تسجيل الوصول | من يجب أن يعرف أن الزائر دخل الآن؟ |
| visitor.checked_out | تسجيل المغادرة | ما الذي يجب إغلاقه أو سحبه الآن؟ |
| visit.overstayed | تجاوز المدة | من يتحقق من زائر بقي بعد وقته؟ |
| document.expiring | قرب انتهاء وثيقة | من يتابع تجديد وثيقة المقاول قبل توقفه؟ |
هذه أمثلة من صفحة الواجهات، والتوثيق الكامل يُسلَّم ضمن المشروع. لا تبنِ تصميمك على اسم حدث أو حقل لم تره في وثائق المورد. إن احتجت حدثًا غير موجود، كرفض زائر عند البوابة، فاكتبه متطلبًا يُبحث في التحليل الفني، أو استخدم الاستعلام عن حالة الزيارة بديلًا.
حالات استخدام Webhooks نظام الزوار حسب الحدث
الحدث الواحد قد يخدم أكثر من نظام. الجدول التالي مصفوفة توجيه نموذجية: من يستهلك كل حدث، وماذا يفعل به، وما الذي يحدث إن تأخر أو تكرر. استخدمها نقطة بداية لجرد حالاتك.
| الحدث | النظام المستقبِل | الإجراء الآلي | أثر التأخر أو التكرار |
|---|---|---|---|
| visit.approved | نظام تذاكر المرافق | فتح تذكرة تجهيز: موقف، قاعة، ضيافة، حساب شبكة ضيوف | التكرار يفتح تذكرة ثانية إن لم يُعالج؛ التأخر مقبول بحدود |
| visit.approved | نظام حجز أو مواعيد خارجي | إبلاغ صاحب الحجز بالاعتماد | التأخر يؤخر الزائر؛ يحتاج مراقبة |
| visitor.checked_in | شاشة غرفة الأمن أو قناة العمليات | تنبيه عند دخول زائر لنوع زيارة أو منطقة حساسة | التأخر يفقد التنبيه قيمته؛ أولوية عالية |
| visitor.checked_in | لوحة إشغال داخلية | زيادة عداد الموجودين حسب الموقع | التكرار يضخم العدد إن لم يُعالج |
| visitor.checked_out | نظام تذاكر المرافق | إغلاق تذكرة التجهيز، وطلب سحب حساب شبكة الضيوف | التأخر يُبقي حسابًا مفتوحًا؛ يحتاج مطابقة |
| visitor.checked_out | أداة قياس الخدمة | حساب مدة البقاء، أو إرسال استبيان رضا من نظام آخر | وصوله قبل حدث الدخول يحتاج معالجة الترتيب |
| visit.overstayed | نظام حوادث الأمن | فتح بلاغ متابعة باسم الزائر والمستضيف والموقع | أولوية عالية؛ التكرار يجب ألا يفتح بلاغين |
| document.expiring | نظام إدارة العقود أو المشتريات | مهمة متابعة لمسؤول العقد، وتسجيل في تقييم المقاول | التأخر ساعات مقبول؛ التكرار يجب ألا يكرر المهمة |
لاحظ أن عمود الأثر هو ما يحدد تصميم المستقبِل لكل حالة. تنبيه غرفة الأمن يحتاج مسارًا سريعًا ومراقبًا، بينما مهمة تجديد الوثيقة تتحمل تأخرًا لكنها لا تتحمل التكرار. وقرب انتهاء الوثيقة تحديدًا لا يغني عن تنبيهات النظام نفسه لمسؤول المقاول؛ الحدث ينقل المعلومة إلى نظام العقود لديك، أما منطق التنبيه والإيقاف فتجده في متابعة انتهاء وثائق المقاول.
الأحداث والإخلاء: نسخة احتياطية لا بديل
حدثا الوصول والمغادرة يتيحان لنظام آخر، كلوحة غرفة التحكم، أن يحتفظ بنسخة من الموجودين لحظيًا. هذا مفيد للاستمرارية، لكنه لا يحل محل إجراء الإخلاء وقائمة الموجودين في النظام نفسه، الذي يطلق الإخلاء ويوزع القوائم على مسؤولي نقاط التجمع ويُعلَّم فيه الحاضرون وتظهر قائمة المفقودين. الصفحة نفسها توصي بتصدير قائمة الموجودين دوريًا إلى أجهزة مسؤولي الطوارئ، وبتحديد خطة الاستمرارية حسب بيئة النشر. وحدث تجاوز المدة أهم هنا مما يبدو: كل زائر تجاوز وقته دون خروج مسجل يُفسد القائمة، وتحويله إلى بلاغ متابعة آلي يرفع دقتها. ومصادر معرفة الموجودين في أي لحظة، من تسجيل الخروج إلى الربط مع أنظمة الحضور، يفصّلها دليل كيف تعرف من يوجد داخل المنشأة الآن.
حدث أم استعلام أم تصدير؟ اختر الأداة المناسبة
ليست كل حاجة تكامل حاجة إلى حدث. ثلاث أدوات، لكل منها موضعه:
| الحاجة | الأداة الأنسب | لماذا |
|---|---|---|
| تصرف فوري عند وقوع شيء | Webhook | يصل لحظة الحدث دون سؤال متكرر |
| معرفة الحالة الحالية عند الحاجة | استعلام API، مثل حالة زيارة أو الموجودون الآن | يعطي الحالة الصحيحة ولو فاتك حدث |
| مطابقة دورية بين نظامين | استعلام مجدول | يكشف ما فات بسبب عطل أو تأخر |
| تحليل واتجاهات وتقارير إدارة | تصدير التقارير أو سحب البيانات لأداة ذكاء الأعمال | لا يحتاج لحظية، ويحتاج بيانات مجمعة |
| نظام قديم لا يستقبل أحداثًا | طبقة تكامل أو ملفات مجدولة | تحول الصيغ أو تتبادل الملفات بقيود معلنة |
أفضل التصاميم تجمع الأداتين الأوليين: الحدث للتصرف السريع، والاستعلام للتحقق والمطابقة. صفحة الواجهات تذكر ضمن أمثلة العمليات الاستعلام عن حالة الزيارة وموافقاتها، وعن الموجودين الآن حسب الموقع، وهما الأداتان اللتان يعود إليهما المستقبِل حين يشك في حدث أو يفوته حدث.
تصميم المستقبِل: الطرف الذي تبنيه أنت
المورد يرسل، لكن أغلب مشكلات الأحداث تظهر في المستقبِل. المخطط التالي يعرض تدفقًا يتحمل الأعطال:
- وقوع الحدثاعتماد أو وصول أو مغادرة أو تجاوز مدة أو قرب انتهاء وثيقةنظام الزوار
- الإرسالطلب إلى عنوان المستقبِل، ويُعاد عند الفشل مع سجل للمحاولاتنظام الزوار
- التحقق والاستلامالتأكد من المصدر والصيغة، ثم رد سريع بالاستلام قبل أي معالجة ثقيلةالمستقبِل
- الطابور ومنع التكرارحفظ الحدث بمعرفه، وتجاهل ما سبقت معالجتهالمستقبِل
- المعالجةتطبيق الإجراء، والاستعلام عن الحالة الحالية عند الشك في الترتيبخدمة المعالجة
- الإجراء في الأنظمة الهدفتذكرة، تنبيه، تحديث لوحة، مهمة متابعةأنظمة المنشأة
قائمة تحقق المستقبِل
- رد سريع ثم معالجة: احفظ الحدث ورد بالاستلام، ثم عالجه بعيدًا عن طلب الإرسال. المعالجة الطويلة داخل الطلب تسبب إعادة إرسال لا داعي لها.
- معالجة مرة واحدة: إعادة الإرسال تعني أن الحدث قد يصل مرتين. خزّن معرفًا لكل حدث معالج وتجاهل المكرر؛ واسأل المورد أي حقل يصلح لذلك.
- تحمل الترتيب: لا تفترض أن المغادرة تصل بعد الوصول دائمًا. قارن وقت الحدث بالحالة المخزنة، أو استعلم عن حالة الزيارة الحالية قبل التصرف.
- أقل بيانات ممكنة: إن كان الحدث يحمل معرفًا فقط، فاستعلم عن التفاصيل بمفتاح صلاحياته محدودة. ولا تنسخ رقم الهوية والصورة إلى أنظمة لا تحتاجها.
- مراقبة الصمت: غياب الأحداث في ساعة يُفترض فيها حركة إشارة عطل. نبه فريقك إن لم يصل حدث وصول واحد في ساعة الذروة.
- مطابقة دورية: قارن ما لديك باستعلام الموجودين الآن بفاصل يناسبك، لتلتقط ما فاتك.
- إجراء استعادة: بعد عطل طويل في المستقبِل، راجع سجل المحاولات لدى المرسل، واتفق مع المورد على طريقة إعادة إرسال ما فشل.
كم حدثًا سيستقبل نظامك؟
مثال افتراضي للتوضيح منشأة تسجل 400 زيارة في اليوم، كلها تمر بالاعتماد والوصول والمغادرة، ويتجاوز المدة 3% منها. ويقع ربع حالات الوصول في ساعة الذروة الصباحية.
- أحداث اليوم = 400 اعتماد + 400 وصول + 400 مغادرة + (400 × 0.03 = 12) تجاوزًا = 1212 حدثًا تقريبًا، قبل أحداث الوثائق.
- أحداث الوصول في ساعة الذروة = 400 × 0.25 = 100 حدث، أي أقل من حدثين في الدقيقة.
- القراءة: الحجم لا يحتاج بنية ضخمة، لكنه يتضاعف عند إعادة الإرسال بعد عطل. صمّم الطابور والسجل لتحمل يوم كامل من الأحداث المتراكمة، لا دقيقة الذروة فقط.
لديك قائمة حالات أتمتة؟ ناقشها مع فريق التطوير في جلسة تقنية، واطلب ملخص الواجهات والأحداث على حالاتك أنت.
ناقش الأتمتة في جلسة تقنيةالتحقق من مصدر الحدث وحماية العنوان
عنوان المستقبِل نقطة دخول إلى أنظمتك. إن قبل أي طلب يصله، فيمكن لأي طرف يعرف العنوان أن يصنع «زائرًا غادر» أو «زيارة اعتُمدت». الضوابط تقع على طرفين:
| الضابط | عند المستقبِل | ما تطلبه من المورد |
|---|---|---|
| إثبات المصدر | رفض أي حدث لا يحمل ما يثبت أنه من نظام الزوار | الآلية المعتمدة لإثبات المصدر (توقيع بسر مشترك، أو شهادة، أو غيرها) وطريقة تغيير السر |
| التشفير | عنوان يعمل عبر HTTPS فقط | تأكيد أن الإرسال لا يتم إلا عبر اتصال مشفر |
| تقييد الشبكة | قبول الطلبات من مصدر النظام فقط حيث يمكن | عناوين الإرسال أو مسار الشبكة المتوقع |
| التحقق من الصيغة | رفض ما لا يطابق الصيغة الموثقة | توثيق محتوى كل حدث وحقوله |
| صلاحيات الاستعلام | مفتاح للمستقبِل بنطاق قراءة ضيق | مفاتيح منفصلة لكل نظام مرتبط بصلاحياته، كما في صفحة الواجهات |
| الأثر | سجل بكل حدث مستلم ونتيجة معالجته | سجل الإرسال والمحاولات لدى النظام |
مكان التشغيل يغير الصورة الشبكية. في النشر على خوادم المنشأة يبقى الإرسال داخل الشبكة، ولا اتصال خارجي إلا لما تسمح به المنشأة، كما في صفحة نظام زوار On-Premise. وفي النشر السحابي يحتاج المستقبِل الداخلي نقطة استقبال تسمح بها سياسة الشبكة لديك، وهذا قرار يشارك فيه فريق الأمن السيبراني مبكرًا. وأسئلة الموثوقية والأمن هذه تتكرر عند تقييم الواجهات كلها، وقائمتها الكاملة في ما الذي تطلبه في وثائق API نظام الزوار.
من الفكرة إلى التشغيل: خطوات مشروع الأتمتة
- جرد الحالات: لكل حالة: الحدث، والنظام المستقبِل، والإجراء، والأولوية، وأثر التأخر والتكرار، كما في مصفوفة التوجيه أعلاه.
- مطابقة الحالات بالوثائق: اطلب ملخص الواجهات والأحداث في مرحلة التقييم، وأسقط أي حالة تعتمد على حدث أو حقل غير موثق، أو حوّلها متطلبًا.
- تصميم المستقبِل: الاستلام والطابور ومنع التكرار والترتيب والمراقبة، قبل كتابة أي إجراء.
- البيئة التجريبية: وجّه الأحداث من بيئة الاختبار إلى نسخة اختبار من المستقبِل، واختبر الأعطال عمدًا: أوقف المستقبِل، وأرسل الحدث مرتين، وغيّر الترتيب.
- التشغيل التدريجي: ابدأ بحالة منخفضة الخطورة، كتذاكر المرافق، ثم أضف تنبيهات الأمن بعد استقرارها.
- التشغيل اليومي: من يراقب سجل المحاولات؟ من يُنبَّه عند الصمت؟ من يملك قرار إعادة الإرسال؟ اكتب الإجابات قبل الإطلاق.
وتذكر أن كل تكامل في النظام يعتمد نطاقه على الأنظمة المتوفرة لدى المنشأة ومدى إتاحتها لواجهات الربط، ويُتحقق منه في التقييم الفني قبل الالتزام، كما تنص صفحة تكاملات نظام إدارة الزوار. الحدث يصل إلى عنوانك؛ أما قدرة نظام التذاكر أو العقود لديك على استقبال ما يصنعه المستقبِل فسؤال يخص ذلك النظام.
سيناريو: شركة مياه بمقر ومركز تحكم
لنفترض شركة مياه إقليمية لها مقر إداري من ستة طوابق، وبجواره مبنى مركز التحكم بقاعة تحكم مقيدة لا يدخلها إلا زوار معتمدون بمرافقة. للموقع بوابتان، ويستقبل يوميًا بين ثمانين ومئة وعشرين زائرًا، إضافة إلى مقاولي صيانة الشبكات والمحطات بعقود سنوية. تعمل غرفة أمن على مدار الساعة، ولدى الشركة نظام تذاكر لخدمات المرافق ونظام لإدارة العقود، وقد اختارت تشغيل نظام الزوار على خوادمها.
جرد فريق تقنية المعلومات اثنتي عشرة فكرة أتمتة، ثم صفّاها بالمصفوفة والوثائق إلى أربع حالات للمرحلة الأولى:
| الحالة | الحدث | القرار |
|---|---|---|
| تنبيه غرفة الأمن عند وصول زائر قاعة التحكم | visitor.checked_in | مرحلة أولى، بمسار سريع ومراقبة صمت |
| تذكرة تجهيز قاعة الاجتماعات والموقف | visit.approved | مرحلة أولى، أول حالة تُشغّل لانخفاض خطورتها |
| بلاغ متابعة لكل تجاوز مدة | visit.overstayed | مرحلة أولى، بمنع صارم للتكرار |
| مهمة تجديد في نظام العقود | document.expiring | مرحلة أولى، بعد التحقق من قدرة نظام العقود على إنشاء المهام آليًا |
| تنبيه عند رفض زائر على البوابة | غير موجود في الأمثلة | كُتب متطلبًا للتحليل، والبديل المؤقت تقرير يومي |
| تحديث لوحة إشغال على شاشات المبنى | الوصول والمغادرة | مؤجل؛ الاستعلام الدوري عن الموجودين يكفي الآن |
في الاختبار على البيئة التجريبية أوقف الفريق المستقبِل نصف ساعة عمدًا، فظهرت المحاولات الفاشلة في سجل الإرسال، ووصلت الأحداث بعد عودته، وكشفت المطابقة مع استعلام الموجودين أن المعالجة لم تفقد شيئًا. وكشف اختبار الإرسال المزدوج أن نظام الحوادث كان سيفتح بلاغين لتجاوز المدة نفسه، فأُضيف تخزين معرفات الأحداث قبل الإطلاق. ومحطات الضخ البعيدة التي يزورها مقاولو الصيانة مرحلة لاحقة، وما يخص المواقع البعيدة والمقاولين والسلامة في هذا النوع من المرافق تجمعه صفحة نظام زوار لشركات الطاقة. ولأن أحداث غرفة الأمن قد تُستخدم لاحقًا في التحقيق، رُبطت سجلات المستقبِل بسياسة الاحتفاظ نفسها التي تحكم سجل التدقيق في نظام الزوار.
الأسئلة الشائعة
صفحة الواجهات تذكر أمثلة: اكتمال الموافقات، وتسجيل الوصول، وتسجيل المغادرة، وتجاوز المدة، وقرب انتهاء وثيقة. القائمة الكاملة ومحتوى كل حدث تُؤكد من التوثيق الذي يُسلَّم ضمن المشروع، ويُقدَّم ملخص الواجهات في مرحلة التقييم.
يُعاد إرسال الحدث عند فشل الاستلام مع سجل بمحاولات الإرسال. صمّم المستقبِل ليتحمل وصول أحداث متراكمة بعد العودة، واتفق مع المورد على طريقة التعامل مع الأعطال الطويلة.
إعادة الإرسال تجعل ذلك واردًا في أي نظام أحداث. لذلك يخزن المستقبِل معرف كل حدث عالجه ويتجاهل المكرر، حتى لا تُفتح تذكرة أو بلاغ مرتين.
الاستعلام يعطي الحالة عند السؤال، والحدث يخبرك لحظة التغيير. للتصرف الفوري استخدم الحدث، وللتحقق والمطابقة استخدم الاستعلام. التصميم الأفضل يجمعهما.
المزايا نفسها في كل خيارات النشر. في النشر على خوادم المنشأة يبقى الإرسال داخل الشبكة، ولا اتصال خارجي إلا لما تسمح به المنشأة، فتكون الأنظمة المستقبِلة الداخلية أسهل وصولًا.
صفحة سجل التدقيق تذكر أن إرسال السجل إلى نظام مراقبة أمنية مركزي ممكن عبر التكامل حسب النظام المستخدم لديكم، ويُحدد نطاقه في التقييم الفني. هذا مسار مختلف عن أحداث الزيارات ويُصمم على حدة.
الخلاصة: ابدأ بالحالات، وابنِ المستقبِل قبل الإجراء
قيمة الأحداث اللحظية في الإجراءات التي تحررها من المكالمات والتقارير المتأخرة: تجهيز قبل الوصول، وتنبيه عند الدخول، وإغلاق عند الخروج، ومتابعة عند التجاوز وقرب الانتهاء. ابدأ بمصفوفة حالاتك، وطابقها بوثائق المورد لا بالافتراض، وابنِ مستقبِلًا يتحقق ويرد بسرعة ويعالج مرة واحدة ويتحمل الترتيب، ثم اختبر الأعطال عمدًا قبل الإطلاق.
إن كانت لديك قائمة أتمتة، فناقشها في جلسة تقنية مع فريق تطوير نظام إدارة زوار المنشآت: ما المتاح من الأحداث والواجهات لحالاتك، وما يحتاج متطلبًا في التحليل، وكيف يُختبر على البيئة التجريبية.