تخطَّ إلى المحتوى

التسليم وإعادة المحاولة ومنع التكرار

تقبل نقطة النهاية عندك التسليم حين ترد بأي رمز حالة 2xx. ينتظر AD80 الرد 10 ثوانٍ على الأكثر، ويقرأ 4 KiB على الأكثر من محتوى ردّك (ويعرضها في سجل الإرسال)، ولا يتبع إعادة التوجيه. تحقّق من التوقيع، واحفظ الحدث، وردّ بـ 2xx، ثم أنجز العمل البطيء بعد ذلك.

ردّكما يفعله AD80
2xxتمّ التسليم.
408، 425، 429، أو أي 5xx، أو انتهاء المهلة، أو خطأ في الشبكةيعيد المحاولة لاحقاً.
أي 4xx آخر (مثل 400، 401، 404)لا يعيد المحاولة، ويُعلَّم التسليم بأنه ميت.
إعادة توجيه (3xx)لا يتبعها، ويعدّ التسليم غير مقبول.

بعد أول فشل تنتظر إعادة المحاولة 30 ثانية تقريباً، وبعد كل فشل جديد تتضاعف المدة (مع تفاوت عشوائي بسيط)، حتى 4 ساعات بين محاولتين. وإن حمل ردّك الترويسة Retry-After فسيلتزم AD80 بها. وبعد 24 ساعة دون نجاح يُعلَّم التسليم بأنه ميت. ويمكنك إرسال التسليم الميت من جديد من سجل الإرسال (أعد الإرسال) أو عبر POST /v1/notifications/deliveries/{id}/redeliver، فيحصل حينها على 24 ساعة أخرى.

ويحدّ AD80 أيضاً من سرعة الإرسال إلى الوجهة الواحدة. والتسليم الذي يتجاوز هذا الحد يتأخّر، لكنه لا يُسقط أبداً.

منع التكرار: اعتمد على معرّف التسليم

Section titled “منع التكرار: اعتمد على معرّف التسليم”

التسليم يحدث مرة واحدة على الأقل. فضياع رد في الشبكة، أو تعطّل في لحظة سيئة، يجعل AD80 يرسل التسليم نفسه مرة أخرى. وكل محاولة لتسليم ما، وكل إعادة إرسال له، تحمل الترويسة X-AD80-Delivery نفسها (وتُرسل أيضاً باسم Idempotency-Key، وفي المحتوى باسم id).

احتفظ بمعرّفات التسليم التي عالجتها (مثلاً في جدول عليه فهرس فريد، لبضعة أيام)، وتجاهل أي تسليم رأيت معرّفه من قبل. أما event_id فيعرّف الحدث الأصلي إن احتجت إليه.

أول ما يصل إلى اشتراك Webhook جديد هو حدث notify.verify (بمعرّف التسليم verify-<subscription id>)، وفيه رمز يُستخدم مرة واحدة. على نقطة النهاية عندك أن تقبله برمز 2xx مثل أي حدث آخر. ثم أعِد الرمز عبر POST /v1/notifications/subscriptions/{id}/confirm، أو أدخله في لوحة المتابعة. وحتى تفعل ذلك لن يُرسل أي حدث آخر.

للاشتراك سرّا توقيع فعّالان على الأكثر. ولتغيير السر دون أن يفوتك أي تسليم:

  1. استدعِ POST /v1/notifications/subscriptions/{id}/rotate-secret. واحفظ السر الجديد من الرد (يظهر مرة واحدة فقط).
  2. من الآن فصاعداً يُوقَّع كل طلب بالسرّين معاً: في X-AD80-Signature إدخالان من نوع v1=.
  3. انشر المستقبِل عندك بالسر الجديد (لا بأس أن يقبل أياً من السرّين أثناء الانتقال).
  4. استدعِ POST /v1/notifications/subscriptions/{id}/retire-secrets. ومن بعدها لا يوقّع إلا السر الأحدث.

وإن احتمل أن يكون السر قد تسرّب، فغيّره فوراً.

  • عناوين https فقط.
  • يجب أن يشير العنوان إلى عنوان عام. تُرفض العناوين الخاصة، وعناوين loopback، وlink-local، وNAT على مستوى المزوّد (carrier-grade NAT)، وعناوين بيانات السحابة الوصفية (cloud metadata). ويتكرّر هذا الفحص مع كل إرسال، ويتصل AD80 بالعنوان نفسه الذي فحصه.