مصطلح
الويب هوك (Webhook)
الويب هوك طلب HTTP يرسله نظام إلى عنوان تحدده أنت لحظة وقوع حدث ما، كإنشاء صفقة أو تحديث جهة اتصال، فيعرف نظامك الآخر بالتغيير فورًا دون أن يسأل عنه كل بضع دقائق.
ما هو الويب هوك؟
الويب هوك (Webhook) آلية تكامل يرسل فيها النظام المصدر طلب HTTP، غالبًا من نوع POST يحمل بيانات بصيغة JSON، إلى عنوان URL يملكه النظام المستقبِل، في اللحظة التي يقع فيها حدث اشترك فيه. فبدل أن يسأل نظام المحاسبة نظام CRM كل خمس دقائق «هل من جديد؟»، وهو ما يُسمى الاستطلاع الدوري (Polling)، يخبره CRM بنفسه فور إنشاء عميل أو تعديل صفقة. ويتكون كل ويب هوك من أربعة عناصر: الحدث الذي يطلقه، والعنوان الذي يستقبله، والحمولة التي تصف ما تغيّر، وتوقيع يثبت أن الطلب جاء فعلًا من المصدر ولم يُعبث به في الطريق. ولأن الشبكات والخوادم تتعطل أحيانًا، فإن المرسل الجيد يعيد المحاولة عند الفشل، والمستقبل الجيد يتحمل وصول الحدث نفسه أكثر من مرة دون أن يكرر أثره.
| المعيار | الويب هوك | الاستطلاع الدوري |
|---|---|---|
| من يبدأ الطلب | المصدر، عند وقوع الحدث | المستقبل، على فترات ثابتة |
| سرعة وصول التغيير | لحظية تقريبًا | بحسب طول الفترة |
| الحمل على الأنظمة | طلب واحد لكل حدث | طلبات متكررة حتى لو لم يتغير شيء |
| ما يحتاجه المستقبل | عنوان عام يقبل الطلبات ويتحقق من التوقيع | صلاحية وصول إلى الواجهة البرمجية |
كيف تستقبل الويب هوك بأمان؟
- تحقق من التوقيع: يحسب المرسل رمز HMAC للحمولة بسر مشترك، وهي آلية يصفها المعيار RFC 2104، فتعيد أنت حسابه بالسر نفسه وتقارن النتيجتين، وترفض الطلب عند أي اختلاف.
- تحقق من الطابع الزمني وارفض الطلبات القديمة، لتمنع إعادة إرسال طلب ملتقط سابقًا.
- رد بسرعة بحالة نجاح ثم عالج الحدث في الخلفية، حتى لا يعدّ المرسل الطلب فاشلًا فيعيد المحاولة.
- اجعل المعالجة آمنة عند التكرار: احفظ معرّف كل إرسال وتجاهل ما سبقت معالجته.
- راقب الإخفاقات، فالعنوان المتعطل قد يؤدي إلى إيقاف الاشتراك أو تراكم الأحداث.
مثال توضيحي: موزع مواد بناء يريد أن يظهر كل عميل جديد في نظامه المحاسبي دون إدخال يدوي. يشترك في حدث إنشاء جهة الاتصال، فيصل نظامَه طلب يحمل الاسم والهاتف والشركة. وفي أحد الأيام يتوقف خادمه ساعة، فيعيد المرسل المحاولة لاحقًا ويصل الحدث نفسه مرتين؛ ولأن المستقبل يحفظ معرّف الإرسال لا يُنشأ العميل مرتين، وهي النتيجة نفسها التي تسعى إليها إزالة البيانات المكررة داخل النظام.
في نافس CRM
يسجّل مسؤولو مساحة العمل في نافس CRM ويب هوك صادرًا من الإعدادات ← التكاملات ← التطبيقات والواجهات البرمجية ← Webhooks، بإدخال اسم وعنوان HTTPS واسم الحدث.
| البند | التفاصيل |
|---|---|
| الأحداث | 9 أحداث: إنشاء جهة الاتصال أو الشركة أو الصفقة وتحديثها وحذفها. وتنشئ الشاشة اشتراكًا لحدث واحد يُكتب باسمه مثل deal.created، أما الأنماط العامة مثل deal.* أو * لكل الأحداث فعبر الواجهة البرمجية |
| الحمولة | خصائص السجل، والحقول المتغيرة في حالة التحديث |
| التوقيع | HMAC-SHA256 في الترويسة X-Naffes-Signature (طابع زمني مع التوقيع)، مع ترويسات X-Naffes-Event وX-Naffes-Delivery-Id وX-Naffes-Webhook-Id |
| إعادة المحاولة | حتى 7 محاولات إجمالًا: بعد 30 ثانية، ثم دقيقتين، ثم 10 دقائق، ثم ساعة، ثم 6 ساعات، ثم 24 ساعة |
| الإيقاف التلقائي | يتوقف الاشتراك تلقائيًا إذا فشل نصف إرسالاته الأخيرة أو أكثر (من 10 إرسالات فأكثر)، ويُستأنف من الشاشة بعد إصلاح العنوان |
| المتابعة | تعرض بطاقة كل ويب هوك نسبة النجاح وعدد الإرسالات خلال 24 ساعة |
وإلى جانب ذلك يستقبل كل من Make وn8n وعنوان Webhook مخصص في متجر التطبيقات حدث deal.stage_changed عند كل تغيير لمرحلة صفقة، لكن هذه الإرسالات بلا توقيع ولا إعادة محاولة. وفي سير العمل خطوة «طلب HTTP» تستدعي أي عنوان خارجي عام وتتيح حالة الاستجابة ومحتواها للخطوات اللاحقة. وتجد خطوات الإعداد وأمثلة التحقق من التوقيع في صفحة تكامل Webhooks.
الباقة وحدود الشاشة: اشتراكات الويب هوك من ميزات باقة Pro فأعلى. ولا تعرض الشاشة من سر التوقيع إلا آخر 4 أحرف، فالتحقق من التوقيع يتطلب حاليًا جلب السر كاملًا من الواجهة البرمجية عند الإنشاء أو التدوير. ولا يمكن من الشاشة ربط اشتراك واحد بعدة أحداث ولا عرض سجل الإرسال. ولا توجد أحداث للمهام أو التذاكر أو الفواتير أو الرسائل، ولا ويب هوك وارد يستقبل طلبات من أنظمة خارجية.
أسئلة شائعة
الأسئلة 2
ما الفرق بين الويب هوك والواجهة البرمجية (API)؟
الواجهة البرمجية تنتظر أن يسألها نظامك، فهو من يبدأ الطلب ليقرأ البيانات أو يغيّرها. أما الويب هوك فيبدأ من المصدر ويخبرك بالتغيير لحظة حدوثه. وفي التكاملات العملية يُستخدمان معًا: الويب هوك ينبّه، والواجهة البرمجية تجلب التفاصيل أو تنفذ التعديل.
لماذا يصلني الحدث نفسه مرتين؟
لأن المرسل يعيد المحاولة إذا لم يتلقَّ ردًا ناجحًا في الوقت المناسب، حتى لو كان طلبه الأول قد وصل. ولهذا يحمل كل إرسال من نافس معرّفًا في الترويسة X-Naffes-Delivery-Id، استخدمه لتجاهل ما عالجته من قبل.