معلومات مفيدة - قيود Webhook وسلوك النظام

فهم كيفية تعامل finlight مع أخطاء webhook وإعادة المحاولات والقيود يساعدك على بناء عمليات دمج أكثر موثوقية وإدارة حصتك بفعالية.

معالجة الأخطاء وإعادة المحاولات

منطق إعادة المحاولة

عند فشل تسليم webhook، يعيد finlight محاولة الطلب تلقائيًا:

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

• إعادة المحاولة الأولى: فور الفشل الأولي مباشرةً
• إعادة المحاولة الثانية
• إعادة المحاولة الثالثة

الحد الأقصى للمحاولات:

• إجمالي 3 محاولات تسليم لكل حدث webhook
• تستخدم كل إعادة محاولة الحمولة والترويسات نفسها
• تُسجَّل جميع محاولات إعادة المحاولة في سجل الاستدعاءات الخاص بك

ما الذي يُطلِق إعادة المحاولات

تحدث إعادة المحاولات في حالات:

• رموز أخطاء HTTP استجابات 4xx و5xx
• مهلات الشبكة (حد 5 ثوانٍ)
• إخفاقات الاتصال (أخطاء DNS، اتصالات مرفوضة)
• أخطاء SSL/TLS (مشكلات الشهادة)

ما الذي لا يُطلِق إعادة المحاولات

لا توجد إعادة محاولات في حالات:

• استجابات HTTP 2xx (تُعدّ ناجحة)
• تهيئة webhook غير صالحة (عناوين URL خاطئة الصياغة)
• webhooks المُعطّلة

حماية التعطيل التلقائي

تتبّع الإخفاقات المتتالية

يتتبّع finlight إخفاقات webhook المتتالية لحماية حصتك ومنع المحاولات الفاشلة التي لا تنتهي.

كيف يعمل:

1. النجاح يعيد ضبط العدّاد - أي تسليم ناجح (HTTP 2xx) يعيد ضبط عدّاد الإخفاق إلى 0
2. الإخفاقات تزيد العدّاد - كل تسليم فاشل يزيد عدد الإخفاقات المتتالية
3. التعطيل التلقائي عند 10 - بعد 10 إخفاقات متتالية، يُعطَّل webhook تلقائيًا

سلوك التعطيل التلقائي

متى يُطلَق التعطيل التلقائي:

• 10 عمليات تسليم فاشلة متتالية عبر جميع محاولات إعادة المحاولة
• تتغيّر حالة webhook من «مُفعّل» إلى «مُعطّل»
• يظهر إشعار في لوحة التحكم يشير إلى التعطيل التلقائي
• لا مزيد من محاولات webhook حتى إعادة التفعيل يدويًا

ملاحظات مهمّة:

• يُحتسَب في التعطيل التلقائي الإخفاقات المتتالية فقط
• أي تسليم ناجح يعيد ضبط العدّاد إلى 0
• مطلوب إعادة تفعيل يدوية - لا تُفعَّل webhooks تلقائيًا
• جميع أنواع الإخفاق تُحتسَب (المهلات، استجابات 4xx، 5xx)

سيناريوهات توضيحية

السيناريو 1: إعادة ضبط العدّاد

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

السيناريو 2: التعطيل التلقائي

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

الاستعادة وإعادة التفعيل

عملية إعادة التفعيل اليدوية

خطوات إعادة التفعيل:

1. حدِّد السبب الجذري باستخدام سجل الاستدعاءات
2. أصلِح مشكلات نقطة النهاية (المصادقة، عنوان URL، أخطاء الخادم)
3. أعد تفعيل webhook في تفاصيل webhook بتعديل إعداد الحالة
4. اختبر webhook يدويًا باستخدام زر الاختبار في لوحة التحكم
5. راقب عمليات التسليم الأولى للتأكّد من الحل

استراتيجيات الوقاية

تجنّب التعطيل التلقائي:

• طبِّق معالجة أخطاء سليمة في نقطة النهاية الخاصة بك
• أرجِع رموز حالة HTTP مناسبة
• راقب سلامة webhook بشكل استباقي
• اضبط تنبيهات لإخفاقات webhook
• اختبر التغييرات في بيئة التطوير قبل الإنتاج

إدارة الحصة

يمكنك رؤية استخدامك على الرسم البياني في لوحة التحكم. ضع في الحسبان أن الاستخدام يُسجَّل بتأخير.

الطلبات الفاشلة تُحتسَب ضمن الحصة

مهم: تُحتسَب جميع محاولات تسليم webhook ضمن حصة اشتراكك، بما في ذلك عمليات التسليم الفاشلة.

ما الذي يُحتسَب:

• محاولات التسليم الأولى - تُحتسَب ضمن الحصة
• جميع محاولات إعادة المحاولة - تُحتسَب كل إعادة محاولة على حدة
• عمليات التسليم الفاشلة - تستهلك الحصة أيضًا
• طلبات اختبار webhook - تُحتسَب أيضًا ضمن الحصة

مثال على تأثير الحصة:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

إدارة الحصة بكفاءة

أفضل الممارسات:

• أصلِح مشكلات نقطة النهاية بسرعة لتقليل عمليات إعادة المحاولة الفاشلة
• راقب سجل الاستدعاءات بحثًا عن أنماط الإخفاق
• اختبر بدقّة قبل تفعيل webhooks في الإنتاج
• استخدم معالجة أخطاء سليمة لإرجاع رموز الحالة الصحيحة

حماية الحصة: تساعد ميزة التعطيل التلقائي على منع هدر الحصة عبر إيقاف عمليات التسليم إلى نقاط النهاية التي تفشل باستمرار.

للحصول على إرشادات إعداد webhook، راجع وثائق webhook الرئيسية. وللاختبار والتصحيح، راجع دليل الاختبار.