التسليم وإعادة المحاولة والفشل

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

تسليم واحد

عند إطلاق حدث، يستلم كل Webhook مفعّل مشترك فيه تسليمًا واحدًا. تنفّذ كل محاولة الخطوات التالية:

الخطوة	التفاصيل
التوقيع	يُؤخذ طابع Unix جديد ويُوقَّع الجسم. راجع التحقق من توقيع Webhook.
الإرسال	طلب POST واحد إلى رابط نقطة النهاية مع Content-Type: application/json وثلاث headers من نوع X-Webhook-*.
الانتظار	حتى 10 ثوانٍ لردّك. يُلغى الطلب بعد ذلك.
الحكم	أي حالة من 200 إلى 299 نجاح. أي حالة أخرى، أو مهلة، أو خطأ اتصال، أو خطأ TLS، تُعد فشلًا.

لا يهم من ردّك إلا رمز الحالة؛ لا يُفسَّر الجسم.

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

يحصل التسليم على 3 محاولات في المجموع. تتضاعف المدة قبل كل إعادة، وتبدأ من 5 ثوانٍ.

المحاولة	الانتظار قبلها	أقرب بداية	أبعد بداية
1	لا شيء	0 ثانية	0 ثانية
2	5 ثوانٍ	5 ثوانٍ	15 ثانية
3	10 ثوانٍ	15 ثانية	35 ثانية

"أقرب بداية" يفترض أن كل محاولة فاشلة تعود فورًا، مثلًا بالرمز 500. "أبعد بداية" يفترض أن كل محاولة تصطدم بمهلة 10 ثوانٍ. في أسوأ الحالات تنتهي المحاولة الأخيرة بعد نحو 45 ثانية من بداية الأولى. أضف هامشًا فوق هذه الأرقام.

تُرسل الإعادات الجسم نفسه. يتغير الطابع الزمني والتوقيع فقط. ينتهي التسليم نهائيًا عندما تحصل محاولة على 2xx، أو بعد المحاولة الثالثة الفاشلة.

أين ترى التسليمات

لا تظهر نتائج التسليم في البوابة. يسرد تبويب خطافات الويب اسم كل Webhook وأحداثه ومعرّفه ونقطة نهايته وحالته. سجّل كل تسليم من جهتك، بما في ذلك headers، حتى تستطيع التحقيق من سجلاتك.

التعطيل التلقائي

العداد يحسب التسليمات الفاشلة المتتالية لكل Webhook، لا المحاولات. يُحتسب التسليم فاشلًا بعد استنفاد المحاولات الثلاث.

الحدث	أثره على العداد
ينتهي التسليم بالحالة failed	يزيد العداد بمقدار 1.
ينتهي التسليم بالحالة delivered	يُصفَّر العداد.
يصل العداد إلى 5	يُعطَّل Webhook، وتعرض البوابة معطّل.
تفعّل Webhook	يُصفَّر العداد.

يُتجاهل Webhook المعطّل عند إطلاق الأحداث، ولا تُرسل الأحداث لاحقًا عند تفعيله. وحفظ نافذة تعديل خطاف الويب ومفتاح تفعيل قيد التشغيل يُصفّر العداد أيضًا.

التعامل مع التكرار

قد يجعل أمران خادمك يرى الحدث نفسه مرتين: إعادة محاولة بعد أن عالج خادمك الحدث لكنه لم يرد خلال 10 ثوانٍ، وspending.exhausted، الذي يُطلق مع كل استدعاء محسوب يترك مفتاحًا عند حده أو فوقه. لا يحمل الجسم معرّف تسليم، لذلك أزل التكرار بالمحتوى:

الحدث	مفتاح إزالة التكرار
job.completed، job.failed	jobId مع header X-Webhook-Event. تنتهي المهمة مرة واحدة، فالتسليم الثاني بالزوج نفسه هو إعادة محاولة.
spending.warning	apiKeyId مع اسم الحدث. يُرسل مرة واحدة في كل دورة فوترة.
spending.exhausted	apiKeyId مع اسم الحدث. عامله كحالة قائمة لا كحدث لحظي: سجّل المفتاح كمستنفد وتجاهل التكرار حتى الدورة التالية.

خزّن المفتاح قبل أن تبدأ العمل، في مخزن يشترك فيه كل نسخ معالجك، واجعل العمل نفسه آمنًا للتشغيل مرتين. وتحدد تجزئة الجسم الخام الإعادة أيضًا، لأن الإعادات تعيد استخدام الجسم بايتًا بايت.

أجب بـ 2xx أولًا، ثم عالج. إذا كانت المعالجة قد تستغرق أكثر من بضع ثوانٍ، فضعها في طابور وأعد الرد فورًا. هذا يبقيك تحت حد 10 ثوانٍ ويتجنب الإعادة التي تسبب معظم التكرار.

موصى به

• تحقق من التوقيع، وسجّل مفتاح إزالة التكرار، وأعد 200، ثم نزّل الصوت أو حدّث سجلاتك من عامل منفصل.

أقل فاعلية

• نزّل الصوت، وحوّله، واكتب في ثلاثة جداول، ثم أعد 200 بعد اثنتي عشرة ثانية، فيُعاد التسليم ويُعالج مرتين.

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

كم مرة ستستدعي نقطة نهايتي لحدث واحد؟

حتى 3 مرات، تفصل بينها نحو 5 ثوانٍ ثم 10 ثوانٍ، إلى أن تحصل محاولة على 2xx. تنتظر كل محاولة حتى 10 ثوانٍ لردك.

هل يُحتسب الرد 200 البطيء تسليمًا ناجحًا؟

لا. الرد الذي يصل بعد 10 ثوانٍ محاولة فاشلة، حتى لو كان 200، ويُعاد التسليم.

هل تُعاد الأحداث الفائتة عند إعادة تفعيل Webhook؟

لا. الأحداث التي أُطلقت أثناء تعطيل Webhook لا تُرسل لاحقًا. استعلم من نقاط نهاية المهام عن أي مهمة انتهت خلال تلك الفترة.

لماذا أوقف Webhook نفسه؟

فشلت 5 تسليمات متتالية بعد استنفاد كل محاولاتها. أصلح نقطة النهاية، ثم فعّل Webhook من جديد؛ يبدأ العداد من صفر.

هل أستطيع رؤية التسليمات السابقة؟

ليس في البوابة. احتفظ بسجلك الخاص لكل تسليم، مع headers الخاصة به، على جهة الاستقبال.

ذو صلة

• إعداد Webhook
• أحداث Webhook
• التحقق من توقيع Webhook