نظام زوار المنشآتمن وقت البيانات لحلول الأعمال

Webhooks في نظام الزوار: أحداث ترسلها إلى أنظمتك وأمثلة استخدامها

الأحداث اللحظية تحول نظام الزوار من مصدر تقارير إلى محرك لإجراءات في أنظمتك. هذا الدليل لفرق تقنية المعلومات: ما الذي يمكن أتمتته بكل حدث، وكيف تبني مستقبِلًا يتحمل الأعطال والتكرار، وما تطلب تأكيده من المورد.

التكامل والتقنيةقراءة 11 دقيقة
الإجابة المختصرة

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، مثل حالة زيارة أو الموجودون الآنيعطي الحالة الصحيحة ولو فاتك حدث
مطابقة دورية بين نظاميناستعلام مجدوليكشف ما فات بسبب عطل أو تأخر
تحليل واتجاهات وتقارير إدارةتصدير التقارير أو سحب البيانات لأداة ذكاء الأعماللا يحتاج لحظية، ويحتاج بيانات مجمعة
نظام قديم لا يستقبل أحداثًاطبقة تكامل أو ملفات مجدولةتحول الصيغ أو تتبادل الملفات بقيود معلنة

أفضل التصاميم تجمع الأداتين الأوليين: الحدث للتصرف السريع، والاستعلام للتحقق والمطابقة. صفحة الواجهات تذكر ضمن أمثلة العمليات الاستعلام عن حالة الزيارة وموافقاتها، وعن الموجودين الآن حسب الموقع، وهما الأداتان اللتان يعود إليهما المستقبِل حين يشك في حدث أو يفوته حدث.

تصميم المستقبِل: الطرف الذي تبنيه أنت

المورد يرسل، لكن أغلب مشكلات الأحداث تظهر في المستقبِل. المخطط التالي يعرض تدفقًا يتحمل الأعطال:

مسار الحدث من نظام الزوار إلى الإجراء في نظامك
  1. وقوع الحدثاعتماد أو وصول أو مغادرة أو تجاوز مدة أو قرب انتهاء وثيقةنظام الزوار
  2. الإرسالطلب إلى عنوان المستقبِل، ويُعاد عند الفشل مع سجل للمحاولاتنظام الزوار
  3. التحقق والاستلامالتأكد من المصدر والصيغة، ثم رد سريع بالاستلام قبل أي معالجة ثقيلةالمستقبِل
  4. الطابور ومنع التكرارحفظ الحدث بمعرفه، وتجاهل ما سبقت معالجتهالمستقبِل
  5. المعالجةتطبيق الإجراء، والاستعلام عن الحالة الحالية عند الشك في الترتيبخدمة المعالجة
  6. الإجراء في الأنظمة الهدفتذكرة، تنبيه، تحديث لوحة، مهمة متابعةأنظمة المنشأة
كيف تقرأه: الخطوتان المميزتان هما قلب التصميم. بوابة التحقق ترفض ما لا يثبت مصدره وترد بسرعة على ما يثبت، حتى لا يعيد المرسل المحاولة بسبب بطء المعالجة. والطابور يفصل الاستلام عن التنفيذ ويمنع تكرار الأثر. إن تعطلت الأنظمة الهدف بقيت الأحداث في الطابور ولم تضع.

قائمة تحقق المستقبِل

  • رد سريع ثم معالجة: احفظ الحدث ورد بالاستلام، ثم عالجه بعيدًا عن طلب الإرسال. المعالجة الطويلة داخل الطلب تسبب إعادة إرسال لا داعي لها.
  • معالجة مرة واحدة: إعادة الإرسال تعني أن الحدث قد يصل مرتين. خزّن معرفًا لكل حدث معالج وتجاهل المكرر؛ واسأل المورد أي حقل يصلح لذلك.
  • تحمل الترتيب: لا تفترض أن المغادرة تصل بعد الوصول دائمًا. قارن وقت الحدث بالحالة المخزنة، أو استعلم عن حالة الزيارة الحالية قبل التصرف.
  • أقل بيانات ممكنة: إن كان الحدث يحمل معرفًا فقط، فاستعلم عن التفاصيل بمفتاح صلاحياته محدودة. ولا تنسخ رقم الهوية والصورة إلى أنظمة لا تحتاجها.
  • مراقبة الصمت: غياب الأحداث في ساعة يُفترض فيها حركة إشارة عطل. نبه فريقك إن لم يصل حدث وصول واحد في ساعة الذروة.
  • مطابقة دورية: قارن ما لديك باستعلام الموجودين الآن بفاصل يناسبك، لتلتقط ما فاتك.
  • إجراء استعادة: بعد عطل طويل في المستقبِل، راجع سجل المحاولات لدى المرسل، واتفق مع المورد على طريقة إعادة إرسال ما فشل.

كم حدثًا سيستقبل نظامك؟

مثال افتراضي للتوضيح منشأة تسجل 400 زيارة في اليوم، كلها تمر بالاعتماد والوصول والمغادرة، ويتجاوز المدة 3% منها. ويقع ربع حالات الوصول في ساعة الذروة الصباحية.

  • أحداث اليوم = 400 اعتماد + 400 وصول + 400 مغادرة + (400 × 0.03 = 12) تجاوزًا = 1212 حدثًا تقريبًا، قبل أحداث الوثائق.
  • أحداث الوصول في ساعة الذروة = 400 × 0.25 = 100 حدث، أي أقل من حدثين في الدقيقة.
  • القراءة: الحجم لا يحتاج بنية ضخمة، لكنه يتضاعف عند إعادة الإرسال بعد عطل. صمّم الطابور والسجل لتحمل يوم كامل من الأحداث المتراكمة، لا دقيقة الذروة فقط.

لديك قائمة حالات أتمتة؟ ناقشها مع فريق التطوير في جلسة تقنية، واطلب ملخص الواجهات والأحداث على حالاتك أنت.

ناقش الأتمتة في جلسة تقنية

التحقق من مصدر الحدث وحماية العنوان

عنوان المستقبِل نقطة دخول إلى أنظمتك. إن قبل أي طلب يصله، فيمكن لأي طرف يعرف العنوان أن يصنع «زائرًا غادر» أو «زيارة اعتُمدت». الضوابط تقع على طرفين:

ضوابط حماية مستقبِل الأحداث
الضابطعند المستقبِلما تطلبه من المورد
إثبات المصدررفض أي حدث لا يحمل ما يثبت أنه من نظام الزوارالآلية المعتمدة لإثبات المصدر (توقيع بسر مشترك، أو شهادة، أو غيرها) وطريقة تغيير السر
التشفيرعنوان يعمل عبر HTTPS فقطتأكيد أن الإرسال لا يتم إلا عبر اتصال مشفر
تقييد الشبكةقبول الطلبات من مصدر النظام فقط حيث يمكنعناوين الإرسال أو مسار الشبكة المتوقع
التحقق من الصيغةرفض ما لا يطابق الصيغة الموثقةتوثيق محتوى كل حدث وحقوله
صلاحيات الاستعلاممفتاح للمستقبِل بنطاق قراءة ضيقمفاتيح منفصلة لكل نظام مرتبط بصلاحياته، كما في صفحة الواجهات
الأثرسجل بكل حدث مستلم ونتيجة معالجتهسجل الإرسال والمحاولات لدى النظام

مكان التشغيل يغير الصورة الشبكية. في النشر على خوادم المنشأة يبقى الإرسال داخل الشبكة، ولا اتصال خارجي إلا لما تسمح به المنشأة، كما في صفحة نظام زوار On-Premise. وفي النشر السحابي يحتاج المستقبِل الداخلي نقطة استقبال تسمح بها سياسة الشبكة لديك، وهذا قرار يشارك فيه فريق الأمن السيبراني مبكرًا. وأسئلة الموثوقية والأمن هذه تتكرر عند تقييم الواجهات كلها، وقائمتها الكاملة في ما الذي تطلبه في وثائق API نظام الزوار.

من الفكرة إلى التشغيل: خطوات مشروع الأتمتة

  1. جرد الحالات: لكل حالة: الحدث، والنظام المستقبِل، والإجراء، والأولوية، وأثر التأخر والتكرار، كما في مصفوفة التوجيه أعلاه.
  2. مطابقة الحالات بالوثائق: اطلب ملخص الواجهات والأحداث في مرحلة التقييم، وأسقط أي حالة تعتمد على حدث أو حقل غير موثق، أو حوّلها متطلبًا.
  3. تصميم المستقبِل: الاستلام والطابور ومنع التكرار والترتيب والمراقبة، قبل كتابة أي إجراء.
  4. البيئة التجريبية: وجّه الأحداث من بيئة الاختبار إلى نسخة اختبار من المستقبِل، واختبر الأعطال عمدًا: أوقف المستقبِل، وأرسل الحدث مرتين، وغيّر الترتيب.
  5. التشغيل التدريجي: ابدأ بحالة منخفضة الخطورة، كتذاكر المرافق، ثم أضف تنبيهات الأمن بعد استقرارها.
  6. التشغيل اليومي: من يراقب سجل المحاولات؟ من يُنبَّه عند الصمت؟ من يملك قرار إعادة الإرسال؟ اكتب الإجابات قبل الإطلاق.

وتذكر أن كل تكامل في النظام يعتمد نطاقه على الأنظمة المتوفرة لدى المنشأة ومدى إتاحتها لواجهات الربط، ويُتحقق منه في التقييم الفني قبل الالتزام، كما تنص صفحة تكاملات نظام إدارة الزوار. الحدث يصل إلى عنوانك؛ أما قدرة نظام التذاكر أو العقود لديك على استقبال ما يصنعه المستقبِل فسؤال يخص ذلك النظام.

سيناريو: شركة مياه بمقر ومركز تحكم

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

جرد فريق تقنية المعلومات اثنتي عشرة فكرة أتمتة، ثم صفّاها بالمصفوفة والوثائق إلى أربع حالات للمرحلة الأولى:

حالات المرحلة الأولى وقرار كل منها
الحالةالحدثالقرار
تنبيه غرفة الأمن عند وصول زائر قاعة التحكمvisitor.checked_inمرحلة أولى، بمسار سريع ومراقبة صمت
تذكرة تجهيز قاعة الاجتماعات والموقفvisit.approvedمرحلة أولى، أول حالة تُشغّل لانخفاض خطورتها
بلاغ متابعة لكل تجاوز مدةvisit.overstayedمرحلة أولى، بمنع صارم للتكرار
مهمة تجديد في نظام العقودdocument.expiringمرحلة أولى، بعد التحقق من قدرة نظام العقود على إنشاء المهام آليًا
تنبيه عند رفض زائر على البوابةغير موجود في الأمثلةكُتب متطلبًا للتحليل، والبديل المؤقت تقرير يومي
تحديث لوحة إشغال على شاشات المبنىالوصول والمغادرةمؤجل؛ الاستعلام الدوري عن الموجودين يكفي الآن

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

الأسئلة الشائعة

صفحة الواجهات تذكر أمثلة: اكتمال الموافقات، وتسجيل الوصول، وتسجيل المغادرة، وتجاوز المدة، وقرب انتهاء وثيقة. القائمة الكاملة ومحتوى كل حدث تُؤكد من التوثيق الذي يُسلَّم ضمن المشروع، ويُقدَّم ملخص الواجهات في مرحلة التقييم.

يُعاد إرسال الحدث عند فشل الاستلام مع سجل بمحاولات الإرسال. صمّم المستقبِل ليتحمل وصول أحداث متراكمة بعد العودة، واتفق مع المورد على طريقة التعامل مع الأعطال الطويلة.

إعادة الإرسال تجعل ذلك واردًا في أي نظام أحداث. لذلك يخزن المستقبِل معرف كل حدث عالجه ويتجاهل المكرر، حتى لا تُفتح تذكرة أو بلاغ مرتين.

الاستعلام يعطي الحالة عند السؤال، والحدث يخبرك لحظة التغيير. للتصرف الفوري استخدم الحدث، وللتحقق والمطابقة استخدم الاستعلام. التصميم الأفضل يجمعهما.

المزايا نفسها في كل خيارات النشر. في النشر على خوادم المنشأة يبقى الإرسال داخل الشبكة، ولا اتصال خارجي إلا لما تسمح به المنشأة، فتكون الأنظمة المستقبِلة الداخلية أسهل وصولًا.

صفحة سجل التدقيق تذكر أن إرسال السجل إلى نظام مراقبة أمنية مركزي ممكن عبر التكامل حسب النظام المستخدم لديكم، ويُحدد نطاقه في التقييم الفني. هذا مسار مختلف عن أحداث الزيارات ويُصمم على حدة.

الخلاصة: ابدأ بالحالات، وابنِ المستقبِل قبل الإجراء

قيمة الأحداث اللحظية في الإجراءات التي تحررها من المكالمات والتقارير المتأخرة: تجهيز قبل الوصول، وتنبيه عند الدخول، وإغلاق عند الخروج، ومتابعة عند التجاوز وقرب الانتهاء. ابدأ بمصفوفة حالاتك، وطابقها بوثائق المورد لا بالافتراض، وابنِ مستقبِلًا يتحقق ويرد بسرعة ويعالج مرة واحدة ويتحمل الترتيب، ثم اختبر الأعطال عمدًا قبل الإطلاق.

إن كانت لديك قائمة أتمتة، فناقشها في جلسة تقنية مع فريق تطوير نظام إدارة زوار المنشآت: ما المتاح من الأحداث والواجهات لحالاتك، وما يحتاج متطلبًا في التحليل، وكيف يُختبر على البيئة التجريبية.

ناقش حالات الأتمتة مع فريق التطوير

اجلب قائمة الحالات التي تريد أتمتتها، ونراجع معك المتاح من الأحداث والواجهات لكل منها، وما يُكتب متطلبًا، وكيف يُختبر على البيئة التجريبية.