شرح Webhook في واتساب API: طريقة ربط واتسيرا مع نظام خارجي
شرح Webhook في واتساب API يبدأ من فكرة بسيطة: بدل أن يسأل نظامك كل عدة ثوانٍ «هل وصلت رسالة جديدة؟»، يرسل النظام المصدر إشعارًا تلقائيًا إلى عنوان تحدده أنت عندما يحدث حدث معين. هذا الإشعار يسمى Webhook. باستخدامه يمكن ربط واتساب أو منصة مثل واتسيرا مع CRM أو متجر أو نظام حجوزات أو تطبيق داخلي بحيث تنتقل الأحداث والبيانات بين الأنظمة لحظة حدوثها.
WhatsApp Business Platform توفر Webhooks ضمن أدوات المطورين لاستقبال الأحداث، بينما تعرض واتسيرا دعم REST API وWebhook ضمن قدرات التكامل الحالية. ولرؤية دور Webhook داخل مسار التفعيل الرسمي راجع دليل تفعيل واتساب API.
ما هو Webhook ببساطة؟
الـWebhook هو طلب HTTP يرسله نظام إلى نظام آخر عند وقوع حدث. غالبًا يكون الطلب من نوع POST ويحمل Payload منظمًا مثل JSON. النظام المستقبل يقرأ البيانات ويقرر ماذا يفعل: إنشاء عميل، تحديث طلب، تشغيل إشعار، حفظ رسالة أو بدء Workflow.
| المصطلح | المعنى |
|---|---|
| Event | الحدث الذي وقع مثل رسالة جديدة أو تغيير حالة |
| Endpoint | الرابط الذي يستقبل الطلب في نظامك |
| Payload | البيانات المرسلة مع الحدث |
| Authentication | طريقة التحقق من أن الطلب قادم من مصدر موثوق |
| Response | رد نظامك لإعلام المصدر أن الطلب استُقبل |
| Retry | إعادة المحاولة إذا فشل التسليم حسب النظام المصدر |
الفرق بين API وWebhook
الـAPI وWebhook يعملان معًا لكنهما ليسا الشيء نفسه. عندما يريد نظامك تنفيذ إجراء في نظام آخر، يستدعي API. أما عندما يريد النظام الآخر إبلاغك بحدث جديد، يستخدم Webhook. مثال: يصل حدث رسالة جديدة عبر Webhook، ثم يقرر نظامك طلب بيانات العميل من CRM أو إرسال إجراء عبر API.
مثال: رسالة واتساب تتحول إلى حدث في CRM
يكتب العميل
يرسل العميل رسالة إلى رقم الأعمال.
يصل الحدث
تستقبل منصة واتساب أو طبقة الإدارة الحدث المرتبط بالمحادثة.
يُرسل Webhook
يُرسل Payload إلى Endpoint النظام الخارجي الذي أعددته.
يتحقق النظام
يفحص المصدر والبيانات ويطابق رقم العميل أو معرفه.
يحدث CRM
ينشئ Lead أو يضيف ملاحظة أو يغير مرحلة العميل حسب منطقك.
يرجع الإجراء
يمكن للنظام لاحقًا استخدام API لإرسال رد أو تشغيل Workflow آخر.
ما البيانات التي يجب إرسالها؟
لا ترسل كل ما لديك لمجرد أنه متاح. صمم Payload بأقل بيانات يحتاجها النظام الآخر لتنفيذ المهمة. من المفيد عادة وجود معرف للحدث، نوع الحدث، وقت حدوثه، معرف جهة الاتصال أو الرقم، والبيانات الخاصة بالعملية. كلما كان Payload ثابت البنية وأسهل في التحقق، قلّ اعتماد التكامل على نصوص غير مضمونة.
إذا كان التكامل يحتوي بيانات شخصية أو حساسة، قلل الحقول وخزّن فقط ما تحتاجه. تجنب وضع أسرار الوصول داخل Payload نفسه، ولا تستخدم رابط Endpoint علنيًا كبديل عن التحقق والمصادقة.
الأمان عند ربط Webhook
- استخدم HTTPS فقط للـEndpoint.
- تحقق من التوقيع أو آلية المصادقة التي يوفرها النظام المصدر عند توفرها.
- لا تعتمد على إخفاء الرابط وحده كوسيلة أمان.
- ضع Rate Limiting وحماية من الطلبات غير المتوقعة عندما يناسب بنيتك.
- لا تسجل Tokens أو أسرار حساسة في Logs.
- اعزل بيئة الاختبار عن الإنتاج قدر الإمكان.
إعادة المحاولة ومنع التكرار
قد يصل الحدث أكثر من مرة بسبب إعادة المحاولة أو مشاكل الشبكة. لذلك يجب أن يكون التكامل قادرًا على استقبال نفس الحدث دون إنشاء الطلب أو العميل مرتين. استخدم Event ID أو مفتاحًا فريدًا عندما يكون متاحًا، واحفظ حالة المعالجة قبل تنفيذ الإجراءات التي يصعب التراجع عنها.
| المشكلة | التعامل الصحيح |
|---|---|
| وصل الحدث مرتين | تحقق من معرف الحدث قبل التنفيذ |
| Endpoint بطيء | أعد ردًا سريعًا ثم عالج المهمة في Queue |
| النظام الخارجي متوقف | خزن المهمة وأعد المحاولة بسياسة محددة |
| Payload ناقص | سجل الخطأ ولا تنفذ إجراءً غير مكتمل |
| فشل الإجراء النهائي | أنشئ سجلًا قابلًا للمراجعة والتنبيه |
كيفية اختبار Webhook قبل الإنتاج
أنشئ Endpoint اختبار
استخدم بيئة غير إنتاجية تستطيع رؤية الطلبات فيها بوضوح.
أرسل حدثًا بسيطًا
ابدأ بنوع حدث واحد فقط بدل ربط جميع الأحداث مرة واحدة.
راجع Payload
تأكد أن أسماء الحقول والقيم مطابقة لما يتوقعه النظام.
اختبر الفشل
أوقف Endpoint مؤقتًا أو أعد خطأً واختبر سلوك إعادة المحاولة.
اختبر التكرار
أرسل الحدث نفسه مرتين وتأكد أن العملية لا تتكرر.
راقب السجلات
أضف Logs مفيدة بلا أسرار حتى تعرف أين يفشل المسار.
ربط واتسيرا مع نظام خارجي
تعرض مميزات واتسيرا REST API وWebhook ضمن أدوات التكامل، ما يسمح ببناء ربط مع أنظمة خارجية بحسب الإمكانيات المتاحة في حسابك. لكن لا تفترض اسم Endpoint أو طريقة Authentication من مقال عام؛ استخدم بيانات الربط والتوثيق الموجودة داخل حسابك أو التي يوفرها فريق الدعم، لأن تفاصيل التنفيذ يجب أن تطابق النسخة الحالية من الخدمة.
ابدأ بحالة استخدام واحدة قابلة للقياس: إرسال Lead إلى CRM، إشعار نظام داخلي بمحادثة جديدة، أو تشغيل إجراء بعد حدث محدد. بعد نجاحها أضف الأحداث الأخرى. هذا يقلل صعوبة اكتشاف الخطأ مقارنة ببناء تكامل كبير دفعة واحدة.
Webhook وواتساب API الرسمي
في الربط الرسمي، Webhooks جزء أساسي من استقبال الأحداث من WhatsApp Business Platform. إذا كنت ما زلت في مرحلة إعداد القناة، اقرأ ما هو واتساب API؟ ثم كيفية تفعيل واتساب API الرسمي قبل بناء تكاملات متعددة فوق قناة لم تُختبر بعد.
أخطاء شائعة
- تنفيذ منطق طويل داخل طلب Webhook قبل إرسال Response.
- عدم وجود معرف يمنع تنفيذ الحدث نفسه مرتين.
- الثقة بأي طلب يصل إلى Endpoint بدون تحقق.
- خلط بيئة الاختبار مع بيانات الإنتاج.
- ربط عشرة أنواع أحداث قبل نجاح أول Event.
- عدم وجود سجل يوضح وقت الاستلام والنتيجة والخطأ.
أسئلة شائعة
هل Webhook هو نفسه REST API؟
لا. REST API يُستخدم غالبًا عندما يطلب نظامك تنفيذ أو جلب شيء، بينما Webhook يدفع الحدث إلى نظامك عند حدوثه.
هل أحتاج خادمًا دائمًا؟
تحتاج Endpoint متاحًا لاستقبال الطلبات عند وقوع الأحداث. يمكن أن يكون ضمن خادمك أو خدمة سحابية مناسبة.
هل يمكن ربط واتسيرا مع CRM؟
من حيث المبدأ توفر واتسيرا REST API وWebhook، لكن تفاصيل الحقول والمصادقة تعتمد على التوثيق والإعداد الفعلي للنظام الذي ستربطه.
كيف أمنع تكرار الطلبات؟
استخدم معرفًا فريدًا للحدث أو العملية واحفظ نتيجة المعالجة بحيث يمكن تجاهل إعادة التسليم بأمان.
حوّل واتساب إلى جزء من نظامك
راجع مميزات واتسيرا وأدوات REST API وWebhook ثم ابدأ بتكامل صغير يمكن اختباره وقياسه قبل التوسع.
عرض مميزات التكاملالخلاصة
Webhook هو الجسر الذي يجعل الأنظمة تتفاعل مع الأحداث فور وقوعها. التكامل الجيد لا يقتصر على إرسال JSON؛ يحتاج Endpoint آمنًا، بنية Payload واضحة، منع التكرار، إعادة محاولة وسجلات قابلة للمراجعة. ابدأ بحدث واحد، اختبر حالات الفشل، ثم وسّع الربط بعد ثبات المسار.