Webhooks واتساب API هي الإشعارات التي تصل إلى خادمك عند حدوث نشاط، مثل استقبال رسالة أو تغير حالة رسالة أرسلها نشاطك. بدل الاعتماد على فحص يدوي متكرر، يستقبل نظامك الحدث ثم يربطه بالمحادثة والإجراء المناسب.
المشكلة ليست استقبال JSON فقط. تحتاج إلى معرفة مصدر الإشعار، والتحقق منه، ومنع تكرار أثره، وفصل وصول الحدث عن نجاح العمل الذي ينفذه نظامك. هذا الدليل يضع قائمة تنفيذ واختبارات، ولا يفترض أن كل مزود يستخدم التوقيع أو شكل البيانات نفسه.
حدد من يرسل الويب هوك
قد تبني اتصالًا مباشرًا مع Meta، أو تستقبل إشعارًا يرسله برنامج إدارة واتساب بعد معالجة الحدث. هذان عقدان مختلفان حتى لو كان أصل الرسالة واحدًا.
| المصدر | المرجع الذي تتبعه | ما لا يجب خلطه |
|---|---|---|
| Meta مباشرة | توثيق Meta لإعداد نقطة الاستقبال والتوقيع | سر التطبيق ليس رمز التحقق أو رمز الوصول |
| منصة إدارة واتساب | عقد الويب هوك الخاص بالمنصة | اسم ترويسة Meta قد يختلف عن ترويسة المزود |
| نظام متجر أو CRM | توثيق مصدر الحدث نفسه | حدث الطلب ليس دليل تسليم رسالة واتساب |
ابدأ من توثيق Meta لنقطة استقبال الويب هوك. وإذا كنت تستقبل إشعارات WA Smart Sender، راجع دليل الويب هوك الخاص بالمنصة بدل نسخ إعداد Meta دون تعديل.
فرق بين التحقق الأولي والتحقق من كل إشعار
التحقق الأولي يثبت أن نقطة الاستقبال تستجيب لإجراء الاشتراك. لكنه لا يغني عن التأكد من صحة كل طلب يحمل حدثًا لاحقًا.
يوضح مرجع Webhooks من Meta توقيع الإشعارات باستخدام سر التطبيق ومقارنته بترويسة X-Hub-Signature-256. لا تستخدم رمز الاشتراك أو رمز إرسال الرسائل مكان سر التوقيع.
احتفظ ببيانات التوقيع في إدارة أسرار الخادم. لا تضعها في كود المتصفح أو روابط عامة أو صور للدعم.
احتفظ بالبايتات الأصلية
صمّم الاستقبال بحيث تستطيع التحقق من جسم الطلب كما وصل، قبل إعادة تنسيقه أو تحويله إلى نص مختلف. إعادة بناء JSON بعد قراءته قد تغير المسافات أو ترتيب المفاتيح، وبالتالي لا تطابق المادة التي وُقعت.
افحص نوع ترويسة التوقيع وصيغتها وطولها قبل المقارنة. الترويسة الناقصة أو المشوهة يجب أن تؤدي إلى رفض واضح، لا استثناء غير معالج أو تنفيذ للحدث.
اختبر جسمًا صحيحًا بتوقيع صحيح، ثم غيّر حرفًا واحدًا في الجسم وأعد الاختبار. الاختبار الناجح الأول وحده لا يثبت أن التحقق يمنع الطلبات غير الصحيحة.
اجعل مسار الاستقبال قصيرًا
كتوصية تصميمية، افصل التحقق والحفظ الموثوق عن الأعمال البطيئة. بعد قبول الحدث في مخزن أو طابور متين، يمكن للعامل المختص تنفيذ تحديث المحادثة أو مزامنة النظام.
لا تعد باستلام ناجح إذا لم تحفظ الحدث بصورة يمكن استعادتها وفق تصميمك. وفي المقابل، لا تجعل استدعاء نموذج ذكاء اصطناعي أو نظام طلبات بطيئًا يحجز اتصال الاستقبال بلا حاجة.
راقب مرحلتين منفصلتين: هل استقبلنا الحدث؟ وهل اكتمل الإجراء؟ قد ينجح الاستقبال وتفشل المعالجة، وهنا تحتاج محاولة داخلية قابلة للمراجعة بدل تجاهل الحدث.
امنع تكرار الأثر
لا تفترض أن كل وصول يمثل نشاطًا جديدًا. صمّم معالجة قابلة لإعادة التنفيذ من دون إعادة إرسال الرد نفسه أو إنشاء تذكرة ثانية.
حدد مفتاحًا يناسب نوع الحدث ومصدره. معرّف الرسالة وحده لا يكفي دائمًا لكل الأحداث المرتبطة بها؛ استقبال حالة جديدة للرسالة نفسها ليس بالضرورة نسخة مكررة من الحالة القديمة.
| الحالة | سلوك موصى به |
|---|---|
| وصول الرسالة الواردة نفسها مرة ثانية | لا تنشئ ردًا آليًا أو سجل محادثة جديدًا |
| وصول حالة تسليم مختلفة للرسالة نفسها | سجل المعلومة الجديدة وفق عقد المصدر |
| إعادة تشغيل العامل أثناء الإجراء | استعد الحالة ولا تبدأ الأثر من الصفر بلا تحقق |
| مهلة غير واضحة أثناء إرسال رد | صالح النتيجة أو استخدم آلية منع التكرار المدعومة |
| حدث لا يعرفه الإصدار الحالي | احتفظ بما يلزم للمراجعة دون تخمين إجراء خطير |
هذه توصيات هندسية؛ تفاصيل المعرفات وإعادة المحاولة والحالات يجب أن تتبع توثيق مصدر الإشعار الفعلي.
لا تفترض ترتيب الوصول
قد تتعامل الأنظمة المتصلة والطوابير مع الأحداث بسرعات مختلفة. احتفظ بوقت المصدر ووقت الاستقبال ونوع الحدث ومعرفه، ولا تعتمد على ترتيب وصول طلبات HTTP وحده لبناء تاريخ المحادثة.
راجع قواعد انتقال الحالة. لا تجعل حدثًا قديمًا يعيد رسالة إلى حالة أقل تقدمًا دون فحص، ولا تحذف تفاصيل فشل مهمة لمجرد وصول إشعار آخر.
عندما تكون البيانات متعارضة، اجعلها قابلة للمراجعة بدل إظهار نجاح نهائي غير مؤكد للموظف أو العميل.
اربط كل حدث بالنطاق الصحيح
احفظ العلاقة بين المؤسسة والاتصال والرقم والمحادثة باستخدام البيانات الموثقة والصلاحيات الداخلية. لا تأخذ معرّف مؤسسة من نص رسالة العميل وتستخدمه لاختيار مساحة عمل.
اختبر وجود رقمين أو عميلين داخل نظام الاختبار. يجب ألا يؤدي حدث أحدهما إلى رد أو تحديث في الآخر. سجل قرارات التوجيه بالقدر الذي يسمح بالتحقيق، مع تقليل البيانات الشخصية وإخفاء الأسرار.
إذا احتجت تمييز WABA ID عن Phone Number ID، طابق كل حقل مع معناه في توثيق التكامل؛ لا تستخدم الرقم الظاهر للعميل بدل معرف مورد API.
اختبارات قبل الإنتاج
- إشعار صحيح بالمصدر والتوقيع المتوقعين.
- ترويسة ناقصة أو بطول غير صحيح.
- تعديل الجسم بعد حساب التوقيع.
- الحدث نفسه يصل مرتين.
- تحديثان يصلان بترتيب مختلف.
- تعطل العامل بعد حفظ الحدث.
- توقف النظام الخارجي مؤقتًا.
- حدث يتبع مؤسسة اختبار أخرى.
- نوع حدث غير معروف.
- إعادة تشغيل الخدمة أثناء إجراء قيد التنفيذ.
لكل حالة حدد النتيجة المتوقعة والنتيجة الفعلية ومسؤول التعافي. استخدم بيانات وأرقام اختبار مصرحًا بها. هذا الدليل لا يدعي أن أي بيئة إنتاج اجتازت الاختبارات.
ما الذي تراقبه؟
تابع فشل التوقيع، وزمن حفظ الحدث، وعمر الطابور، وفشل المعالجة، والنسخ المكررة، والإجراءات التي لم تصل إلى نتيجة معروفة. اربط التنبيه بمالك وإجراء قابل للتنفيذ، لا بعدد كبير من رسائل التحذير فقط.
افصل قياس وصول الويب هوك عن قياس تسليم رسالة واتساب أو حل طلب العميل. راجع دليل تقارير حملات واتساب للحفاظ على الفرق بين الإشعار التقني والنتيجة التجارية.
قائمة تسليم التكامل
وثق مصدر الأحداث، والترويسات، وآلية التحقق، ومفتاح منع التكرار، وحالات الفشل، وسياسة المحاولة والاحتفاظ، وصلاحيات الوصول. ثم سلم اختبارات قابلة لإعادة التشغيل وسجلًا لنتائجها.
لتحديد ما تدعمه WA Smart Sender حاليًا راجع مرجع API ودليل الويب هوك. تحقق من الخطة المناسبة في صفحة الأسعار والصلاحيات والعقد الفعلي قبل ربط التدفق بعملاء حقيقيين.
