دليل webhooks واتساب: كيف تستقبل أحداث رسائلك لحظياً

الجواب المختصر: الـwebhook هو رابط (URL) في سيرفرك يرسل له واتساب طلب HTTP فوري كل ما يصير حدث جديد، مثل وصول رسالة من عميل أو تغيّر حالة تسليم رسالة أرسلتها. بدل ما يسأل نظامك واتساب كل ثانية "فيه جديد؟"، واتساب نفسه يدق بابك أول ما يصير الحدث، فتستقبل البيانات لحظياً وبأقل استهلاك للموارد.

في هذا الدليل نمشي معاك خطوة خطوة: وش هو الـwebhook ببساطة، فرقه عن الـpolling، أنواع الأحداث اللي تستقبلها من واتساب، كيف تجهّز endpoint يستقبلها، كيف تأمّنه عبر التحقق من التوقيع، وأهم حالات الاستخدام العملية.

وش هو الـwebhook ببساطة

تخيّل إنك طلبت توصيل طلب، فبدل ما تتصل بالمطعم كل خمس دقائق تسأل وين وصل الطلب، المطعم نفسه يرسل لك رسالة أول ما يطلع الطلب من المطبخ وأول ما يوصل عندك. هذا بالضبط هو الـwebhook في عالم البرمجة.

تقنياً، الـwebhook عبارة عن endpoint (رابط) تجهّزه أنت في سيرفرك، وتسجّله عند مزوّد الخدمة. كل ما يصير حدث مرتبط بحسابك، يرسل المزوّد طلب HTTP من نوع POST لهذا الرابط، ويكون جسم الطلب (body) بصيغة JSON يحتوي تفاصيل الحدث. مهمتك إنك تستقبل هذا الطلب، تقرأ البيانات، وترد بـ200 OK بسرعة عشان تأكد للمزوّد إنك استلمت.

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

الفرق بين webhook والـpolling

في طريقتين تعرف فيهما إن فيه حدث جديد: الـpolling والـwebhook. في الـpolling نظامك يسأل واتساب كل فترة قصيرة "فيه رسائل جديدة؟"، حتى لو ما فيه شي جديد، فأنت تستهلك طلبات وموارد على الفاضي وتدخل تأخير بمقدار الفترة بين كل سؤال والثاني.

أما في الـwebhook فأنت ما تسأل أبداً، لأن واتساب هو اللي يرسل لك أول ما يصير الحدث. النتيجة استجابة شبه فورية بزمن أقل من ثانية مع عدد طلبات أقل بكثير، لأنه ما فيه طلبات على الفاضي.

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

أنواع أحداث واتساب اللي تستقبلها

واتساب يرسل لك أنواع متعددة من الأحداث، وكل نوع له استخدامه. أهمها:

• الرسائل الواردة (message): أهم حدث على الإطلاق، يُطلق أول ما يرسل لك عميل رسالة نصية أو صورة أو ملف أو ردة فعل، ويحمل محتوى الرسالة ورقم المرسل ووقتها.
• حالة الرسالة (message status): يخبرك إن رسالة أرسلتها صارت مُرسَلة (sent) أو وصلت (delivered) أو انقرأت (read) أو فشلت (failed).
• الردود على القوالب والأزرار: يُطلق لما يضغط العميل زر أو يختار من قائمة تفاعلية أو يرد على رسالة قالب.
• أحداث الجلسة والاتصال: مثل تغيّر حالة ربط الرقم أو انقطاع الجلسة، تنفعك لمراقبة صحة الحساب.

الجدول التالي يربط كل حدث بوقت إطلاقه واستخدامه العملي:

نوع الحدث | متى يُطلق | الاستخدام

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

كيف تجهّز endpoint يستقبل

تجهيز نقطة الاستقبال أبسط مما تتوقع. تحتاج رابط عام (HTTPS إلزامي) يقبل طلبات POST. خطوات العمل:

1. أنشئ مسار في تطبيقك مثل /webhooks/whatsapp يستقبل POST.
2. اقرأ جسم الطلب بصيغة JSON وفكّ ترميزه.
3. تحقق من التوقيع قبل ما تثق بالبيانات (نشرحه بعد قليل).
4. عالج الحدث بسرعة أو ادفعه لطابور (queue) عشان تعالجه بالخلفية.
5. رُد فوراً بـ200 OK، لأن أي تأخير أو خطأ يخلي واتساب يعيد المحاولة.

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

مثال مبسّط لجسم طلب رسالة واردة:

{
  "event": "message.received",
  "data": {
    "from": "966500000000",
    "type": "text",
    "text": "السلام عليكم، عندكم الطلب جاهز؟",
    "timestamp": 1718500000
  }
}

أمان الـwebhook والتحقق من التوقيع

رابط الـwebhook عام، فأي أحد يعرفه يقدر يرسل له بيانات مزيّفة. عشان كذا التحقق من التوقيع مو خياري، هو ضروري. الفكرة إن واتس لووب يحسب توقيع HMAC للرسالة باستخدام مفتاح سري تعرفه أنت وحدك، ويرسله في رأس (header) مع كل طلب، فأنت تعيد حساب نفس التوقيع على جسم الطلب الخام وتقارنه.

خطوات التحقق:

1. خذ جسم الطلب الخام كما وصل قبل أي تعديل.
2. احسب HMAC-SHA256 للجسم باستخدام مفتاحك السري.
3. قارن الناتج مع قيمة التوقيع في الرأس مقارنة آمنة ثابتة الزمن.
4. لو ما تطابقت، ارفض الطلب فوراً بـ401 ولا تعالج شي.

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

حالات استخدام عملية

الـwebhooks هي العمود الفقري لأي أتمتة جدية على واتساب. أبرز ما تبنيه فوقها:

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

كل هذي السيناريوهات تبدأ من نفس النقطة: endpoint يستقبل الحدث لحظياً. مع واتساب API من واتس لووب، تجهّز رابط الـwebhook وتسجّله بدقائق، وتبدأ تستقبل كل أحداث حسابك بتوقيع موثّق وصيغة JSON واضحة، فتبني فوقها أتمتتك بثقة. جرّب الربط اليوم وخلّ نظامك يسمع عملاءك أول بأول.