التحقق من نقطة نهاية خطاف الويب (webhook) في WhatsApp

ماذا ترسل Meta بالضبط؟

ترسل طلب GET إلى عنوان URL الخاص بك مع ثلاث معلمات في سلسلة الاستعلام. تكون قيمة hub.mode هي subscribe. أما hub.verify_token فهي الرمز الذي أعددته عند ضبط الوجهة. وhub.challenge قيمة تنشئها Meta لهذه المحاولة.

يجب أن تقارن نقطة النهاية hub.verify_token بالرمز الذي اخترته، وإذا تطابقا، فأعد استجابة بالرمز 200 يكون نصها الكامل هو hub.challenge. لا تضعه داخل JSON، ولا تحطّه بين علامتي اقتباس، ولا تضف سطرًا جديدًا في النهاية كما تفعل بعض أطر العمل افتراضيًا.

إذا لم يتطابق الرمز، فأعد 403. هذا هو البروتوكول كاملًا، وقد صُمم ليكون صغيرًا عمدًا.

لماذا يفشل الرد الخاطئ بصمت؟

لأن فشل التحقق ليس خطأً في نظامك، بل غيابًا في نظام Meta.

عندما لا يُعاد التحدي بشكل صحيح، لا تبدأ Meta ببساطة التسليم إلى تلك الوجهة. يعيد خادمك 200 لطلب التحقق، وتظهر في سجلاتك عملية وصول الطلب، ولا تعرض أي لوحة تحكم مشكلة. العرض الوحيد هو أن الرسائل لا تصل، ولذلك يشخّص معظم الناس المشكلة على أنها مشكلة في Coexistence، لا مشكلة في المصافحة.

لهذا يستحق التحقق قبل إجراء الطلب. نتحقق من أن عنوان URL يستخدم HTTPS ومن توفير رمز تحقق قبل إجراء طلب Graph، حتى تفشل الوجهة غير الصحيحة فورًا بدل أن تبدو متصلة.

ما الأمور الأخرى التي قد تمنع التحقق؟

ثلاثة أمور لا علاقة لها بالشفرة.

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

إعادة التوجيه. تستدعي Meta عنوان URL الذي قدمته، ولا تُتبع عملية إعادة توجيه 301 إلى مضيف أساسي بطريقة تُكمل المصافحة. قدم لها العنوان النهائي.

وإطار عمل يحوّل الاستجابة إلى صيغة متسلسلة. إن أعدت سلسلة نصية من معالج يضع كل شيء داخل JSON، فسيحتوي النص على علامتي اقتباس حول التحدي، ولن يطابق القيمة المطلوبة.

الأخطاء الشائعة

• إرجاع JSON. يجب أن يحتوي النص على قيمة التحدي الخام وحدها دون أي شيء حولها.
• وضع نقطة النهاية خلف المصادقة. لا تملك Meta بيانات اعتماد وستُرفض.
• تقديم عنوان URL يعيد التوجيه إلى Meta. استخدم العنوان النهائي.

الأسئلة الشائعة

تابع القراءة