فشل التحقق من توقيع الويب هوك على خادمك

ماذا يعني ذلك#

كل رسالة ويب هوك نرسلها موقّعة. يعيد خادمك حساب التوقيع ويقارنه بالترويسة X-DS-Signature؛ فإذا اختلفا يرفض كودك الرسالة، مثلاً بالرد 401. ولا تستطيع المنصة رؤية المقارنة، فهي ترى ردّ HTTP الذي ترسله فقط، لذلك يظهر عدم التطابق كإرسال فاشل: يعرض عمود «الرد» في سجل الرسائل الرمز (مثل 401)، وتعرض نافذة التفاصيل وسطر «آخر إرسال» للرابط نص الخطأ «رد نظامك 401» (بالإنجليزية: Your system response 401). ويُحفظ هذا النص وقت الإرسال بلغة الجلسة آنذاك، فقد تظهر الرسائل الأقدم أو التي أُرسلت في الخلفية بلغة أخرى؛ والرمز الرقمي هو المؤشر الموثوق.

من المتأثر#

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

الأسباب المحتملة#

التوقيع هو sha256= متبوعاً بالتمثيل السداسي العشري (hex) بأحرف صغيرة لناتج HMAC-SHA256، والرسالة المُوقَّعة هي قيمة X-DS-Timestamp ثم نقطة ثم جسم الطلب الخام (raw body) كما وصل تماماً، والمفتاح هو مفتاح التوقيع كاملاً بما فيه whsec_.

كيف تشخّص المشكلة#

1. أرسل تجربة. في لوحة التاجر افتح «الويب هوك والـ API» ثم «إدارة الويب هوك». وفي لوحة الشركة افتح «الربط والـ API» ثم «إدارة الروابط والسجل». اضغط «إرسال تجربة» على الرابط (يظهر للروابط المفعّلة فقط). تُرسل رسالة ping بالتوقيع نفسه، وحقل data فيها يحمل بيانات آخر طرد في حسابك، أو message بنص تجربة قصير إن لم يوجد طرد. والنتيجة: «وصلت رسالة التجربة لنظامك (الرد 200).» أو «ما وصلت: …». وعبر الـ API يفعل POST /api/v1/webhooks/{id}/test الشيء نفسه، لكن الحقل data فيه يحمل دائماً message بنص تجربة قصير وليس بيانات طرد.

2. افتح سجل الرسائل. يعرض كل صف رمز الرد. ويُظهر زر العين ما أرسلناه وردّ نظامك (أول 2000 حرف)، وكثيراً ما يحتوي على نص «توقيع غير صالح» الذي كتبته أنت. والبيانات هناك معروضة بعد إعادة تنسيقها، ولا يُحفظ التوقيع ولا الطابع الزمني، لذلك لا يمكن إعادة حساب التوقيع منها.

3. سجّل من جهتك الجسم الخام وX-DS-Timestamp وX-DS-Signature، ثم أعد الحساب يدوياً:

   bashنسخ

   ( printf '%s.' "$TIMESTAMP"; cat body.raw ) | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
   

   يجب أن تساوي النتيجة بالنظام السداسي العشري قيمة الترويسة بعد sha256=. فإن تطابقت فالخلل في كود التحقق لديك، وإلا فالمفتاح أو جسم الطلب.

4. قارن نتيجة كودك بمثال الاختبار المرجعي (test vector) في دليل التحقق من التوقيع.

خطوات الحل#

1. تحقق من جسم الطلب الخام

   اقرأ البايتات قبل أي تحليل لـ JSON، وأوقف التحليل التلقائي للجسم في هذا المسار.

2. استخدم المفتاح الصحيح

   افتح «مفتاح التوقيع» للرابط (زر العين يعرضه وزر النسخ ينسخه). واحفظ السلسلة كاملة، بما فيها البادئة whsec_، دون مسافات. وبعد «تجديد» يتوقف المفتاح القديم فوراً، فحدّث خادمك أولاً.

3. أصلح فحص الوقت

   خذ الطابع الزمني من الترويسة واستخدمه بالثواني، وأبقِ ساعة الخادم متزامنة.

4. جرّب من جديد ثم أعد الإرسال

   اضغط «إرسال تجربة». وتُعاد الرسائل الفاشلة تلقائياً بعد دقيقة و5 و30 دقيقة، ثم ساعتين و6 و12 و24 ساعة، أي 8 محاولات بالمجموع. ولتتجنب الانتظار اضغط «إعادة إرسال» على الصف.

ماذا يحدث أثناء الفشل#

بعد 40 إرسالاً فاشلاً متتالياً، بما فيها التجارب وإعادة المحاولات، يُوقَف الرابط ويظهر سبب إيقافه. أصلح خادمك، ثم اضغط «تعديل» وحدّد خانة «مفعّل» واحفظ؛ فيبدأ العدّاد من جديد. ويحتفظ السجل بآخر 30 يوماً.

متى تتواصل مع الدعم#

• إذا طابق توقيعك المعاد حسابه الترويسة ومع ذلك يرفض خادمك الرسالة.
• إذا أبلغ «إرسال تجربة» بعبارة «ما وصلت» مع خطأ يخص العنوان، رغم أن رابطك HTTPS عام.
• اذكر دائماً المعرّف evt_ ووقت الرسالة؛ فكلاهما في السجل.