الأمان

موثوقية الـ webhook تعتمد بنفس القدر على سلوك نقطة النهاية الخاصة بك كما تعتمد على ضمانات التسليم لدى Unico. تغطي هذه الصفحة القواعد الثلاث التي يجب أن تحترمها نقطة النهاية: الأمانة (Idempotency)، حد التزامن (Concurrency Limit)، ومعدل الأخطاء (Error Rate).

الأمانة (Idempotency)

يضمن تطبيق الـ webhook في Unico التسليم مرة واحدة على الأقل — قد يتم إرسال إشعار بنفس الحالة أكثر من مرة لنفس processId. يجب أن تكون نقطة النهاية مضمونة الأمانة.

النمط الموصى به:

1. عند كل استدعاء للـ webhook، تحقق أولاً مما إذا كان processId قد تمت معالجته مسبقاً.
2. إذا كان كذلك، أعد 2xx فوراً (العمل تم بالفعل).
3. إذا لم يكن كذلك، طبّق منطق عملك واحفظ حقيقة أن هذا processId قد تمت معالجته.

// pseudo-code
async function handleWebhook(req, res) {
  const { processId } = req.body;

  if (await alreadyProcessed(processId)) {
    return res.status(200).end();
  }

  await applyBusinessLogic(req.body);
  await markAsProcessed(processId);
  return res.status(200).end();
}

لماذا هذا مهم

نقطة نهاية غير مضمونة الأمانة تُشغّل منطق الأعمال عند كل تسليم (مثل خصم بطاقة، أو إرسال بريد إلكتروني) ستنفّذ العملية مرات متعددة عند حدوث إعادة محاولة — وإعادة المحاولة أمر طبيعي، وليس استثناءً، في تسليم الـ webhook.

حد التزامن (Concurrency Limit)

لحماية نقطة النهاية من الارتفاعات المفاجئة خلال فترات الحجم العالي، قم بتهيئة الحد الأقصى لعدد عمليات التسليم المتزامنة قيد التنفيذ (الحد الأقصى: 500) عند تسجيل الـ webhook.

عند الوصول إلى حد التزامن، تقوم Unico بوضع عمليات التسليم الإضافية في قائمة انتظار ومعالجتها عند توفر السعة. مع إعادة المحاولات، يعني هذا أن الارتفاع المستمر يمكن أن يمدد وقت التسليم الفعلي للـ webhooks الجديدة.

معدل الأخطاء (Error Rate)

يجب أن يكون معدل الأخطاء (الردود خارج نطاق 200–299) منخفضاً دائماً. إذا بدأت نقطة النهاية في إعادة الأخطاء على نطاق واسع، فإن Unico تُقلل تلقائياً من إنتاجية الـ webhook لتلك النقطة. مع آلية إعادة المحاولة، يمكن أن يزيد هذا بشكل ملحوظ من وقت تنفيذ الـ webhooks الجديدة.

إرشادات التشغيل:

• راقب ردود غير 2xx من طرفك. أنشئ تنبيهاً عند معدلات أخطاء مستمرة تتجاوز خط الأساس العادي.
• تعامل مع معالج الـ webhook الخاص بك باعتباره مساراً حيوياً — يجب أن يكون من أكثر الخدمات موثوقية في بنيتك.
• للصيانة المجدولة، يُفضّل إيقاف استقبال الطلبات على مستوى موزع الأحمال بدلاً من إعادة 503. الردود المتكررة خارج نطاق 2xx — بما فيها 503 — تُفعّل تقليل الإنتاجية التلقائي المذكور أعلاه؛ وعند استعادة نقطة النهاية، تؤدي الإنتاجية المنخفضة إلى تأخير تسليم الأحداث المتراكمة خلال فترة الانقطاع. لا تُعيد 200 عند فشل المعالجة.

دلالات الحالة (Status Semantics)

تعامل مع مجموعة قيم state وlastEvent باعتبارها إعداداً قابلاً للتطور:

• استجب فقط للحالات / الأحداث التي تتعامل معها صراحةً.
• سجّل القيم غير المعروفة — لا توقف التنفيذ بسببها.
• قد تُضاف حالات جديدة دون تغيير رئيسي في الإصدار.