التسليم وإعادة المحاولة ومنع التكرار
ردّ بسرعة برمز 2xx
Section titled “ردّ بسرعة برمز 2xx”تقبل نقطة النهاية عندك التسليم حين ترد بأي رمز حالة 2xx. ينتظر AD80 الرد 10 ثوانٍ على الأكثر، ويقرأ 4 KiB
على الأكثر من محتوى ردّك (ويعرضها في سجل الإرسال)، ولا يتبع إعادة التوجيه. تحقّق من التوقيع، واحفظ الحدث،
وردّ بـ 2xx، ثم أنجز العمل البطيء بعد ذلك.
إعادة المحاولة
Section titled “إعادة المحاولة”| ردّك | ما يفعله 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 فيعرّف الحدث الأصلي إن احتجت إليه.
مصافحة التأكيد
Section titled “مصافحة التأكيد”أول ما يصل إلى اشتراك Webhook جديد هو حدث notify.verify (بمعرّف التسليم verify-<subscription id>)، وفيه رمز
يُستخدم مرة واحدة. على نقطة النهاية عندك أن تقبله برمز 2xx مثل أي حدث آخر. ثم أعِد الرمز عبر
POST /v1/notifications/subscriptions/{id}/confirm، أو أدخله في لوحة المتابعة. وحتى تفعل ذلك لن يُرسل أي حدث آخر.
تغيير السر
Section titled “تغيير السر”للاشتراك سرّا توقيع فعّالان على الأكثر. ولتغيير السر دون أن يفوتك أي تسليم:
- استدعِ
POST /v1/notifications/subscriptions/{id}/rotate-secret. واحفظ السر الجديد من الرد (يظهر مرة واحدة فقط). - من الآن فصاعداً يُوقَّع كل طلب بالسرّين معاً: في
X-AD80-Signatureإدخالان من نوعv1=. - انشر المستقبِل عندك بالسر الجديد (لا بأس أن يقبل أياً من السرّين أثناء الانتقال).
- استدعِ
POST /v1/notifications/subscriptions/{id}/retire-secrets. ومن بعدها لا يوقّع إلا السر الأحدث.
وإن احتمل أن يكون السر قد تسرّب، فغيّره فوراً.
قواعد الوجهة
Section titled “قواعد الوجهة”- عناوين
httpsفقط. - يجب أن يشير العنوان إلى عنوان عام. تُرفض العناوين الخاصة، وعناوين loopback، وlink-local، وNAT على مستوى المزوّد (carrier-grade NAT)، وعناوين بيانات السحابة الوصفية (cloud metadata). ويتكرّر هذا الفحص مع كل إرسال، ويتصل AD80 بالعنوان نفسه الذي فحصه.