دور الـ webhooks في معالجة رسائل WhatsApp API الفورية

يرسل عميل رسالة إلى رقم WhatsApp Business API الخاص بك في الساعة 2:00 مساءً. يستقبل خادم Meta الرسالة. والسؤال هو: كيف يعرف نظام عملك أن رسالة جديدة قد وصلت؟ هناك طريقتان: يسأل خادمك Meta باستمرار (polling)، أو تُخطر Meta خادمك فور وصول رسالة جديدة (webhook).

الاستطلاع مكلف وبطيء. يستهلك خادمك موارد مستمرة في طرح سؤال «هل هناك رسالة جديدة؟» كل بضع ثوانٍ، وقد يصل زمن الاستجابة للعميل إلى عشرات الثواني.

الـ webhooks فعّالة وتعمل في الوقت الفعلي. ترسل Meta بيانات الرسالة تلقائيًا إلى خادمك خلال أجزاء من الثانية بعد وصول الرسالة. وهذه هي الآلية القياسية لـ WhatsApp Business API، وهي الأساس الذي تقوم عليه روبوتات المحادثة والردود التلقائية والتكامل مع CRM في الوقت الفعلي.

يشرح هذا الدليل ما هي الـ webhooks، وأحداث WhatsApp API التي يمكن تفعيلها، وكيف تُعدّ webhook، والأخطاء الشائعة التي ينبغي الاستعداد لها، وأفضل الممارسات لبناء أنظمة جاهزة للإنتاج.

المزايا الرئيسية

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

ما هو الـ webhook؟

الـ webhook هو آلية يقوم فيها نظام (في هذه الحالة Meta) بإرسال البيانات تلقائيًا إلى نظام آخر (خادم عملك) عند وقوع حدث معيّن. وعلى خلاف الـ API المعتادة التي تطلب فيها البيانات، فإن الـ webhook عملية ‘push’: فـ Meta هي من يرسل البيانات بشكل نشط.

تقنيًا، يعمل الـ webhook عبر طلب HTTP POST: ترسل Meta طلب POST إلى URL تسجله أنت (عادةً ما يُسمّى نقطة استقبال الـ webhook)، مع حمولة تحتوي على بيانات الحدث. يعالج خادمك الحمولة ويرد بـ HTTP 200 OK ضمن حد زمني محدد (عادةً 20 ثانية).

في حالة WhatsApp Business API، يُعدّ الـ webhook الطريقة الأساسية لاستقبال الرسائل الواردة وتحديثات حالة الرسائل. وبدون webhook، سيكون التكامل مع WhatsApp API محدودًا جدًا.

أحداث WhatsApp API التي يمكن تفعيلها

ترسل Meta عدة أنواع من الأحداث عبر الـ webhook. وأهمها لعمليات العمل:

الرسائل الواردة. رسائل جديدة من العملاء. تحتوي الحمولة على رقم المرسل، ومحتوى الرسالة (نص أو صورة أو مستند أو وسائط أخرى)، والطابع الزمني، ومعرّف الرسالة.

تحديثات حالة الرسائل. تحديثات حالة الرسائل التي ترسلها الشركة: تم الإرسال، تم التسليم، تمت القراءة، فشل. وهي مفيدة لتتبّع معدل التسليم ومعدل القراءة.

تحديثات حالة القوالب. إشعارات عندما توافق Meta على رسائل القوالب أو ترفضها أو تعلّم عليها بسبب مشكلات في الجودة.

تنبيهات الحساب. تغييرات حالة مهمة مثل انخفاض تصنيف الجودة، أو تغيّر مستوى الرسائل، أو مخالفة السياسات. وهذا مهم جدًا لمراقبة سلامة الحساب.

التفاعلات على الرسائل. عندما يتفاعل العملاء مع رسالة شركتك برمز تعبيري (إيموجي).

تسجّل الشركات عادةً webhooks لكل أنواع الأحداث هذه، حتى لو لم تتم معالجة بعضها كلها. وتسجيل كل الأحداث يجعل النظام جاهزًا عند ظهور احتياجات جديدة.

للاطلاع على سياق أوسع حول WhatsApp Business API ومكوّناته، راجع WhatsApp Business API: دليل شامل.

كيفية إعداد webhook

يتطلب إعداد الـ webhook ثلاثة مكوّنات: نقطة استقبال URL، ورمز التحقق، وبروتوكول HTTPS.

نقطة استقبال العنوان (URL). عنوان URL الخاص بخادم عملك الذي سيستقبل طلبات POST من Meta. مثال: `https://api.your-business.com/webhook/whatsapp`. ويجب أن يكون العنوان عامًا ويمكن الوصول إليه من Meta.

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

HTTPS. ترسل Meta الـ webhooks إلى عناوين HTTPS فقط، ولا يُقبل HTTP غير المشفّر. ويجب أن تكون شهادة SSL صالحة وغير موقّعة ذاتيًا.

بعد جهوزية هذه المكوّنات الثلاثة، يتم إعداد الـ webhook في لوحة تحكم WhatsApp Business Platform أو عبر BSP. ويتطلب الإعداد الأولي عملية تحقق من Meta: ترسل Meta رمز التحقق ويجب أن يرد خادمك بالصدى المناسب.

الأخطاء الشائعة التي ينبغي الاستعداد لها

تعطل الخادم أو بطء الاستجابة
إذا لم يستجب خادمك خلال 20 ثانية، تعتبر Meta ذلك فشلًا وتعيد المحاولة. وتتكرر المحاولات بفترات أطول تدريجيًا. وإذا استمر الفشل، قد تعطّل Meta الـ webhook مؤقتًا.

فقدان الأحداث بسبب التوقف
عندما يكون الخادم معطّلًا لعدة ساعات، قد تُفقد الأحداث التي تصل خلال تلك الفترة إذا فشلت محاولات Meta. وفي الأنظمة الجاهزة للإنتاج، استخدم نظام طابور (مثل RabbitMQ أو AWS SQS) لتخزين الأحداث في ذاكرة وسيطة قبل معالجتها.

فشل التحقق من التوقيع
توقّع Meta كل طلب بتوقيع يمكن التحقق منه. وإذا تم تجاوز هذه الخطوة، يصبح النظام عرضة لـ webhooks مزيفة. تحقّق دائمًا من التوقيع قبل معالجة الحمولة.

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

لفهم دور BSP في إدارة الـ webhooks وتوفير نقطة استقبال مُدارة، راجع ما هو WhatsApp BSP؟.

أفضل الممارسات للأنظمة الجاهزة للإنتاج

استجب بسرعة، وعالج بشكل غير متزامن
ينبغي لنقطة استقبال الـ webhook أن تقبل الحمولة فحسب، وتضعها في الطابور، وترد فورًا بـ 200 OK. أما المعالجة الفعلية (استدعاء الذكاء الاصطناعي، وتحديث الـ CRM، وما شابه) فتُنفّذ بشكل غير متزامن بواسطة عامل منفصل. وهذا يُبقي زمن استجابة الـ webhook أقل من ثانية واحدة.

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

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

معالجة إعادة المحاولة
للمعالجة غير المتزامنة التي تفشل (مثل تعطل خدمة الذكاء الاصطناعي)، نفّذ إعادة المحاولة مع تراجع أُسّي (backoff) وقائمة رسائل ميتة (dead letter queue) للأحداث التي تفشل مرارًا.

أمن أبعد من التوقيع
التحقق من التوقيع هو الحد الأدنى. وللبيانات الحسّاسة، أضف مصادقة على مستوى الشبكة (مثل قائمة عناوين IP المسموح بها لـ Meta) وشفّر الحمولة أثناء التخزين.

أين تقع حزمة الأدوات

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

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

لمعرفة تفاصيل قدرات WhatsApp Business API التي تشمل بنية webhook مُدارة، راجع صفحة WhatsApp Business API.

من أين تبدأ

إذا كنت تبني تكاملًا مع WhatsApp API من الصفر، ابدأ بإعداد الـ webhook في بيئة اختبار قبل الإنتاج. أرسل بعض رسائل الاختبار وتحقق من وصول الأحداث بشكل صحيح، ومن التحقق من التواقيع، ومن بقاء زمن الاستجابة أقل من ثانية واحدة.

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

إذا كنت تستخدم BSP مثل Cekat، فمعظم تعقيد الـ webhook قد تمت معالجته بالفعل. ويمكنك أن تركّز على منطق العمل بدلًا من البنية التحتية.

فعّل أتمتة WhatsApp الفورية

كل ثانية بلا webhook يعمل فيها هي ثانية لا يستطيع فيها روبوت المحادثة أن يرد، ويتأخر فيها التكامل مع CRM، ويفقد فيها فريق خدمة العملاء سياق الرسائل الواردة. وللشركات التي توسّعت بالفعل إلى مئات أو آلاف المحادثات يوميًا، ليس الـ webhook اختياريًا؛ بل هو الأساس.

إذا أردت استخدام webhook لتشغيل روبوتات محادثة ذكية وأتمتة فورية دون بناء البنية التحتية بنفسك، فإن روبوت محادثة WhatsApp بالذكاء الاصطناعي من Cekat يقدّم روبوتات محادثة مدمجة بالفعل مع webhooks Meta وجاهزة للاستخدام.

ابدأ تجربة مجانية لترى روبوت محادثة يعمل في الوقت الفعلي على WhatsApp تحدّث مع فريقنا للحصول على استشارة حول إعداد webhook وأتمتة WhatsApp تناسب احتياجاتك