إعادة محاولة الويب هوك والإيقاف التلقائي

الغرض#

يوضح هذا المرجع ما الذي يحدث حين لا يردّ نظامك على رسالة ويب هوك: متى تُعاد المحاولة، ومتى يُوقَف الرابط تلقائياً، وكيف تستعمل سجل الرسائل وإعادة الإرسال.

ما الذي يُعدّ نجاحاً أو فشلاً#

• النجاح: رد HTTP من فئة 2xx خلال 10 ثوانٍ.
• الفشل: أي رد آخر، ومنه 3xx (لا تُتَّبع إعادة التوجيه، ويطلب نص الخطأ الظاهر في السجل تسجيل الرابط النهائي)، وانتهاء المهلة، وأخطاء DNS أو الاتصال أو TLS، وفشل فحص العنوان العام وقت الإرسال. يُحفظ نص الخطأ.
• المحاولة الأولى تُجرى فور وقوع الحدث (بعد انتهاء الطلب الذي سبّبه). أما المحاولات اللاحقة فتتولاها مهمة مجدولة.

جدول إعادة المحاولة#

• المجموع 8 محاولات. بعد الثامنة تصير الرسالة «فشل» ولا تُعاد تلقائياً (استعمل «إعادة إرسال»).
• الأوقات هي الحد الأدنى: المهمة المجدولة (webhooks:retry) تعمل كل دقيقة وتعالج حتى 100 رسالة مستحقة في الدورة، فقد تتأخر كل محاولة نحو دقيقة.
• تحمل كل المحاولات الجسم وX-DS-Event-Id وX-DS-Delivery نفسها، ويتغير X-DS-Attempt وX-DS-Timestamp وX-DS-Signature.
• رسائل التجربة (ping) لا تُعاد تلقائياً.
• الترتيب غير مضمون وقد تتكرر الرسالة؛ تجاهل المكرر بحسب X-DS-Event-Id.

الإيقاف التلقائي#

• لكل رابط عدّاد للمحاولات الفاشلة المتتالية: كل محاولة فاشلة (لأي رسالة، ومنها التجربة) تزيده 1، وأي محاولة ناجحة تصفّره.
• عند 40 يصبح الرابط غير مفعّل («موقوف») ويُحفظ سبب مثل «توقف تلقائياً بعد 40 محاولة فاشلة متتالية — آخر خطأ: ...». يظهر السبب بالأحمر تحت الرابط في اللوحة، ويعود في الحقل disabled_reason في GET /api/v1/webhooks.
• العدّاد يحسب المحاولات لا الرسائل؛ رسالة واحدة تفشل محاولاتها الثماني تضيف 8.
• الرابط الموقوف لا يتلقى أحداثاً جديدة ولا تُخزَّن له. والرسائل التي كانت بانتظار الإعادة تُعلَّم «فشل» (بخطأ «الرابط موقوف أو محذوف») حين يحين دورها، دون إرسال، إن بقي الرابط موقوفاً؛ أما إن أعدت تفعيله قبل ذلك فتُرسل بشكل طبيعي. وحذف الرابط من اللوحة يُعلِّم رسائله المعلّقة «فشل» فوراً (بخطأ «الرابط انحذف»)؛ أما حذفه عبر DELETE /api/v1/webhooks/{id} فلا يمسّها، وتُعلَّم «فشل» (بخطأ «الرابط موقوف أو محذوف») دون إرسال حين يحين موعد إعادة محاولتها.

سجل الرسائل#

يظهر في أسفل صفحة «الويب هوك الصادر» تحت عنوان «سجل الرسائل — آخر 30 يوم» (في اللوحة فقط):

• الأعمدة: «الوقت» و«الحدث» و«الرابط» و«الحالة» (نجح، بانتظار إعادة المحاولة، فشل، مع موعد المحاولة التالية) و«الرد» (رمز HTTP والمدة بالميلي ثانية) و«المحاولات».
• أيقونة العين تفتح نافذة فيها «اللي بعتناه» (الجسم) و«رد نظامك» (رمز HTTP وأول 2000 حرف من الرد)، مع معرّف الحدث وعدد المحاولات والرابط والخطأ.
• الفلاتر: الرابط والحدث والحالة، وبحث برقم التتبع أو evt_ أو UUID. 25 رسالة في الصفحة.
• يحفظ السجل بيانات آخر محاولة فقط لكل رسالة. وتُحذف الصفوف الأقدم من 30 يوماً بتنظيف كل ساعة.
• إعادة إرسال: زر على كل صف (يظهر والرابط مفعّل). يُرسل فوراً حتى لو نجحت الرسالة سابقاً، ويُحتسب محاولة إضافية (يزيد X-DS-Attempt). وإن فشلت إعادة الإرسال وكان رقم المحاولة 7 أو أقل جُدولت المحاولة التالية بحسب الجدول، أما من المحاولة 8 فصاعداً فتبقى الرسالة «فشل».

التعافي بعد انقطاع الخدمة#

1. أصلح نقطة النهاية

   اجعلها ترد 2xx. حدّد السبب من عمود «الرد» ومن نافذة تفاصيل الرسالة.

2. أعد تفعيل الرابط الموقوف

   اضغط «تعديل» ثم علّم «مفعّل» واضغط «حفظ»؛ يُصفَّر العدّاد ويُمسح سبب الإيقاف. ويستطيع التاجر ذلك أيضاً عبر الـ API: PATCH /api/v1/webhooks/{id} مع {"active": true}؛ أما مدير الشركة فيستعمل اللوحة (واجهة الشركة لا تتضمن مسارات للويب هوك).

3. جرّب بـ «إرسال تجربة»

   يظهر الزر عندما يكون الرابط مفعّلاً. التجربة الناجحة تصفّر العدّاد وتؤكد أن نظامك يتحقق من التوقيع ويردّ.

4. أعد إرسال الرسائل الفاشلة

   في «سجل الرسائل» اختر الحالة «فشل» واضغط «إعادة إرسال» على كل رسالة تحتاجها. أما الرسائل التي ما زالت بانتظار إعادة المحاولة فتُرسل حين يحين دورها.

5. عوّض الأحداث الفائتة

   لأن الأحداث لا تُخزَّن أثناء الإيقاف، اقرأ حالة طرودك: التاجر بـ GET /api/v1/parcels أو GET /api/v1/parcels/{tracking}، ومدير الشركة بـ GET /api/company/v1/parcels (مع الفلتر updated_since) أو GET /api/company/v1/parcels/{tracking}.

أخطاء شائعة#

• رابط يعيد التوجيه (مثل https://example.com إلى https://www.example.com، أو مسار يحوّل إلى صفحة تسجيل دخول): 3xx تُعدّ فشلاً. سجّل الرابط النهائي.
• معالجة تستغرق أكثر من 10 ثوانٍ قبل الرد: ردّ 2xx فوراً وعالج في الخلفية.
• رد 4xx على أحداث لا تهمك: يُعدّ فشلاً فيُعاد الإرسال ثم يُوقَف الرابط. أعد 2xx وتجاهل الحدث.
• رد 401 بعد تجديد مفتاح التوقيع: حدّث المفتاح في نظامك، فكل رسالة ترفضها تُحسب محاولة فاشلة.

الصلاحيات والحدود#

• الصلاحية نفسها كما في مقالة الويب هوك: التاجر من لوحته، ومدير الشركة من «الربط والـ API».
• «إعادة إرسال» محدود بـ 30 في الدقيقة، و«إرسال تجربة» بـ 10 في الدقيقة.