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

1) نموذج التسليم الأساسي

مرة واحدة على الأقل (افتراضي) - سيتم تسليم الحدث ≥1 مرات. يتم تحقيق الضمانات مرة واحدة بالضبط من خلال حماقة المتلقي.
الإقرار (ACK): فقط أي 2xx (عادة 200/204) من المتلقي يعني النجاح. كل شيء آخر يفسر على أنه فشل ويؤدي إلى التكرار.
Fast ACK: رد 2xx بعد وضع الحدث بدوره، وليس بعد المعالجة الكاملة للأعمال.

2) شكل الحدث والعناوين الإلزامية

الحمولة (مثال)

json
{
"id": "evt_01HXYZ",
"type": "order. created",
"occurred_at": "2025-11-03T18:10:12Z",
"sequence": 128374,
"source": "orders",
"data": { "order_id": "o_123", "amount": "49. 90", "currency": "EUR" },
"schema_version": 1
}

رؤوس المرسل

معرف X-Webhook: evt_01HXYZ' - معرف حدث فريد (استخدم للتفريغ).
«X-Webhook-Seq: 128374» - تسلسل رتيب (حسب الاشتراك/السمة).
التوقيع السيني: sha256 = <base64 (hmac_sha256 (الجسم، السر))> - HMAC- подпись.

"X-Retry: 0,1,2... هو رقم المحاولة

«X-Webhook-Version: 1» - إصدار العقد.
(اختياري) "Traceparent' - ارتباط أثر.

رد من المتلقي

2xx - تم قبوله بنجاح (لن يكون هناك تكرار آخر لهذا 'id').
410 ذهب - نقطة النهاية محذوفة/مرسل → غير نشط ينهي عمليات إعادة التشغيل ويعطل الاشتراك.
429/5xx/مهلة - يكرر المرسل وفقًا لسياسة إعادة الدفع.

3) سياسة الإعادات

سلم التراجع الموصى به (+ jitter)

1، 3، 10، 30، 2 م، 10 م، 30 م، 2 ساعة، 6 ساعة، 24 ساعة (توقف بعد الحد، على سبيل المثال 48-72 ساعة).

• التراجع الأسي + الترنح العشوائي (± 20-30٪) لتجنب «تأثير القطيع».
• نصاب الأخطاء للفشل المؤقت (على سبيل المثال، إعادة المحاولة إذا كان 5xx أو مهلة الشبكة).
• احترم 429: ضبط الحد الأدنى من «الحد الأدنى» (إعادة النظر بعد الرأس، النافذة الخلفية التالية).

المهلات والأحجام

مهلة الاتصال ≤ 3-5 ثوان ؛ إجمالي مهلة الاستجابة ≤ 10 ثوان

حجم الجسم بموجب العقد (على سبيل المثال، ≤ 256 كيلوبايت)، وإلا فإن 413 → المنطق «القطع» أو «سحب عنوان URL».

4) الخصوصية والتفريط

التطبيق اللطيف: معالجة التكرارات لنفس «اليد» يجب أن تعيد نفس النتيجة ولا تغير الحالة مرة أخرى.
تخزين Dedup على جانب المستلم: متجر '(X-Webhook-Id، processed_at، checksum' مع نوافذ TTL ≥ إعادة تشغيل (24-72 ساعة).
المفتاح التركيبي: إذا → عدة مواضيع '(subscription_id، event_id)'.

5) الطلب و «التأثيرات مرة واحدة بالضبط»

• التقسيم حسب المفتاح: نفس المجموعة المنطقية (على سبيل المثال، 'الطلب _ id') تكون دائمًا في «قناة» واحدة من التسليم.
• التسلسل: ارفض الأحداث باستخدام «X-Webhook-Seq» القديم ووضعها في «ساحة انتظار السيارات» قبل وصول المفقودين.

• سجل العمليات المطبقة (نمط outbox/inbox)،
• اضطراب المعاملات من خلال 'event _ id' في قاعدة البيانات،
• ملاحم/تعويضات عن العمليات المعقدة.

6) حل الخطأ حسب رموز الحالة (الجدول)

7) أمن القناة

توقيع HMAC لكل رسالة ؛ تحقق من جهاز الاستقبال باستخدام «النافذة الزمنية» (هجمات القفازات وإعادة التشغيل).
TLS للمجالات الحساسة (LCC/المدفوعات).
IP allowist للعناوين الصادرة، TLS 1. 2 +، HSTS.
التقليل من مؤشر الاستثمار الدولي: لا ترسل بيانات شخصية غير ضرورية ؛ التنكر في جذوع الأشجار.
تدوير الأسرار: مفتاحان صالحان (نشطان/تاليان) ورأس "X-Key-Id' للإشارة إلى المفتاح الحالي.

8) قوائم الانتظار و DLQs والإعادة

يجب كتابة الأحداث إلى قائمة انتظار/سجل المخرجات على جانب المرسل (لإعادة التشغيل بشكل موثوق).
إذا تم تجاوز الحد الأقصى لإعادة التدوير، فإن الحدث يذهب إلى DLQ (قائمة انتظار الحروف الميتة) مع السبب.
إعادة تشغيل واجهة برمجة التطبيقات (للمستلم/المشغل): إعادة تقديم 'هوية '/نطاق زمني/موضوع، مع تقييد RPS والتوقيع/الإذن الإضافي.

POST /v1/webhooks/replay
{ "subscription_id": "sub_123", "from": "2025-11-03T00:00:00Z", "to": "2025-11-03T12:00:00Z" }
→ 202 Accepted

9) العقد والنسخة

نسخة الحدث (حقل 'المخطط _ النسخة') والنقل ('X-Webhook-Version').
تضاف الحقول باعتبارها اختيارية فقط ؛ على الحذف - الهجرة الطفيفة والفترة الانتقالية (الكتابة المزدوجة).
أنواع الأحداث المستندية، أمثلة، المخططات (مخططات JSON)، رموز الخطأ.

10) إمكانية الرصد و SLO

• «تسليم _ نجاح _ معدل» (2xx/جميع المحاولات)، 'first _ failure _ success _ rate'
• «retries _ total»، «max _ retry _ age _ seconds'،» dlq _ count'
• 'latency _ p50/p95' (occurred_at → ack_received_at)

• «ack _ latency» (تلقي → 2xx)، «processing _ latency» (استفسار → تم)
• 'duplicates _ total', 'invalid _ signature _ total', 'out _ of _ order _ total'

99. 9٪ من الأحداث تتلقى أول ACK ≤ 60 ثانية (28 د).

• DLQ ≤ 0. 1 في المائة من المجموع ؛ إعادة تشغيل DLQ ≤ 24 ساعة.

11) التوقيت وفواصل الشبكة

استخدام التوقيت العالمي المنسق في المجالات الزمنية ؛ تزامن NTP.
أرسل «حدث _ at' وأصلح» تم تسليمه _ at' لقراءة التأخير.
مع فترات الراحة الطويلة، → تتراكم الشبكة/نقطة النهاية في قائمة الانتظار، وتحد من النمو (الضغط الخلفي + الحصص).

12) الحدود الموصى بها والنظافة

RPS لكل اشتراك (على سبيل المثال 50 RPS، انفجار 100) + تزامن (على سبيل المثال 10).
ماكس. الهيئة: 64-256 كيلوبايت ؛ للمزيد - «إشعار + عنوان URL» وتوقيع التنزيل.
أسماء الأحداث في الأفعى. حالة 'أو' نقطة. نوع '(' طلب. أنشئت ').
الخصوصية الصارمة لعمليات الكتابة للمستقبل.

13) أمثلة: المرسل والمستلم

13. 1 مرسل (كاذب)

python def send_event(event, attempt=0):
body = json. dumps(event)
sig = hmac_sha256_base64(body, secret)
headers = {
"X-Webhook-Id": event["id"],
"X-Webhook-Seq": str(event["sequence"]),
"X-Retry": str(attempt),
"X-Signature": f"sha256={sig}",
"Content-Type": "application/json"
}
res = http. post(endpoint, body, headers, timeout=10)
if 200 <= res. status < 300:
mark_delivered(event["id"])
elif res. status == 410:
deactivate_subscription()
else:
schedule_retry(event, attempt+1) # backoff + jitter, respect 429 Retry-After

13. 2 جهاز استقبال (كاذب)

python
@app. post("/webhooks")
def handle():
body  = request. data headers = request. headers assert verify_hmac(body, headers["X-Signature"], secret)
evt_id = headers["X-Webhook-Id"]
if dedup_store. exists(evt_id):
return, "" 204 enqueue_for_processing (body) # fast path. dedup_store put(evt_id, ttl=723600)
return, "" 202 # or 204

14) ممارسات الاختبار والفوضى

الحالات السلبية: توقيع غير صحيح، 429/5xx، مهلة، 410، حمولات كبيرة.
السلوك: خارج النظام، مكرر، تأخير من 1-10 دقائق، استراحة لمدة 24 ساعة.
الحمولة: انفجار 10 × ؛ تحقق من الضغط الخلفي ومثابرة DLQ.
العقود: مخطط JSON، العناوين الإلزامية، أنواع الأحداث المستقرة.

15) قائمة التنفيذ المرجعية

• 2xx = ACK، والعودة السريعة بعد الاستفسار
• تراجع أسي + نفض الغبار، احترام 'Retry-After'
• جهاز الاستقبال IDempotency و X-Webhook-Id (TTL ≥ Retray)
• توقيعات HMAC، تناوب سري، mTLS اختياري
• DLQ + إعادة تشغيل واجهة برمجة التطبيقات والرصد والتنبيهات
• الحدود: المهلة، RPS، حجم الجسم
• الأمر: التقسيم حسب المفتاح أو «التسلسل» + «موقف السيارات»
• الوثائق: المخططات، والأمثلة، ورموز الأخطاء، والنسخ
• اختبارات الفوضى: التأخير، التكرار، فشل الشبكة، إعادة التشغيل الطويلة

16) الأسئلة الشائعة المصغرة

هل أحتاج دائما للإجابة 200 ؟

أي 2xx يعتبر نجاحًا. 202/204 ممارسة عادية لـ «قبولها في قائمة الانتظار».

هل يمكن إيقاف الإعادة ؟

نعم، رد 410 و/أو عبر وحدة تحكم المرسل/واجهة برمجة التطبيقات (إلغاء الاشتراك).

ماذا عن الحمولات الكبيرة ؟

أرسل «إشعار + عنوان URL آمن»، ووقع طلب التنزيل وثبت TTL.

كيف تضمن النظام ؟

التقسيم حسب المفتاح + 'التسلسل' ؛ في حالة التناقض - «موقف للسيارات» وإعادة التشغيل.

المجموع

خطافات الويب الموثوقة هي دلالات ACK (2xx) واضحة، وتكرارات معقولة مع التراجع + النفاخ، والغباء الصارم والتفريغ، والأمن الكفء (HMAC/mTLS)، وقوائم الانتظار + إعادة DLQ +، وإمكانية المراقبة الشفافة. قم بإصلاح العقد، وإدخال الحدود والمقاييس، وتشغيل سيناريوهات الفوضى بانتظام - وستتوقف عمليات الدمج الخاصة بك عن «التدفق» عند الإخفاقات الأولى.