خطوط الويب وفراغ الأحداث

TL; د

خطاف الويب الجيد هو حدث موقع (HMAC/mTLS)، تم تلخيصه وتقديمه على نموذج مرة واحدة على الأقل مع التراجع الأسي والتفريغ عند المستلم. اتفق على مظروف ('event _ id'، 'type'، 'ts'،' نسخة '،' محاولة '،' توقيع ')، نافذة زمنية (≤5 دقائق)، رموز الاستجابة، عمليات إعادة التصوير، DLQ ونقطة النهاية للحالة.

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

المرسل (أنت/المزود): يولد حدثًا، وعلامات، ويحاول تسليم ما يصل إلى 2xx، وإعادة السمة عند 3xx/4xx/5xx (باستثناء «لا تقبل» الصريح)، يقود DLQ، يعطي إعادة تشغيل API.
المستلم (الشريك/خدمتك): يتحقق من نافذة التوقيع/الوقت، ويقوم بالتخلص من المعالجة والخصوصية، ويستجيب بالرمز الصحيح، ويوفر/الحالة و/إعادة التشغيل بواسطة «event _ id».

الضمانات: مرة واحدة على الأقل. يجب أن يكون المتلقي قادرًا على التعامل مع النسخ المكررة وإعادة الترتيب.

2) مظروف الحدث

json
{
"event_id": "01HF7H9J9Q3E7DYT5Y6K3ZFD6M",
"type": "payout.processed",
"version": "2025-01-01",
"ts": "2025-11-03T12:34:56.789Z",
"attempt": 1,
"producer": "payments",
"tenant": "acme",
"data": {
"payout_id": "p_123",
"status": "processed",
"amount_minor": 10000,
"currency": "EUR"
}
}

الحقول المطلوبة هي «event _ id' و» type «و» version «و» ts' و «ts» و «tery».
قواعد التطور: إضافة حقول ؛ حذف/تغيير الأنواع - فقط مع «النسخة» الجديدة.

3) الأمن: التوقيعات والملزمة

3. 1 توقيع HMAC (التوصية الافتراضية)

X-Signature: v1=base64(hmac_sha256(<secret>, <canonical>))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF7...

<timestamp>\n<method>\n<path>\n<sha256(body)>

• abs (الآن − X-Timestamp) ≤ 300
• لم تتم معالجة "X-Event-Id' قبل (التخلص)
• مطابقات «X-Signature» (مقارنة آمنة للوقت)

3. 2 تدابير

mTLS لخطابات الويب شديدة الحساسية.
قائمة السماح IP/ASN.
DPoP (اختياري) للمرسل المقيد إذا بدأ الخطاف الويب عمليات إعادة الاتصال.

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

4. 1 إفراط الحدث

• المتاجر 'event _ id' في المخبأ الأبله (KV/Redis/DB) على TTL ≥ 24-72 ساعة ؛
• يحفظ نتيجة المعالجة (النجاح/الخطأ، القطع الأثرية) لإعادة إعادتها.

4. 2 أمر الخصوصية (إعادة الاتصال)

إذا أجبر الخطاف العميل على سحب واجهة برمجة التطبيقات (على سبيل المثال، «تأكيد الدفع»)، فاستخدم «Idempotency-Key» في مكالمة REST، وقم بتخزين النتيجة على جانب الخدمة (نتيجة مرة واحدة بالضبط).

key: idempotency:event:01HF7...
val: { status: "ok", processed_at: "...", handler_version: "..." }
TTL: 3d

5) Retrai والتراجع

• 5، 15، 30، 1 م، 2 م، 5 م، 10 م، 30 م، 1 ساعة، 3 ساعة، 6 ساعة، 12 ساعة، 24 ساعة (ثم يوميًا حتى أيام N)

• 2xx - النجاح، توقف عن إعادة التدوير.

• «400/ 401/403/404/422» - لا يمكن سحبها إذا كان التوقيع/الشكل على ما يرام (خطأ العميل).
• «429» - retrayim بواسطة «Retry-After» أو التراجع.
• 5xx/الشبكة - retrayim.

رؤوس المرسل: «User-Agent»، «X-Webhook-Producer»، «X-Fetture».

6) المعالجة الجانبية لجهاز الاستقبال

pseudo verify_signature()
if abs(now - X-Timestamp) > 300s: return 401

if seen(event_id):
return 200 // идемпотентный ответ

begin transaction if seen(event_id): commit; return 200 handle(data)       // доменная логика mark_seen(event_id)    // запись в KV/DB commit return 200

المعاملات: يجب تعيين الملصق «المرئي» ذريًا مع تأثير العملية (أو بعد تثبيت النتيجة) لتجنب المعالجة المزدوجة عند الفشل.

7) ضمانات النظام واللقطات

النظام غير مضمون. استخدام 'ts' و' seq '/' نسخة 'في' البيانات 'للتحقق من الأهمية.
للتأخيرات/الخسائر الطويلة - أضف/أعد التشغيل عند المرسل و/resync عند جهاز الاستقبال (احصل على لقطة ودلتا في نافذة الوقت/الهوية).

8) الحالة والإعادة و DLQ

8. 1 نقاط نهاية المرسل

«POST/webhooks/replay» - حسب قائمة «event _ id» أو حسب نافذة الوقت.
«احصل على/خطابات الويب/الأحداث/: معرف» - أظهر حزمة المصدر وتاريخ المحاولات.
DLQ: أحداث «ميتة» (تم استنفاد حد إعادة الدفع) → تخزين منفصل، تنبيهات.

8. 2 نقاط نهاية المستلم

"GET/ webhooks/status/:event_id' -" seen = true/fall'، "processed _ at'،" handler _ version ".
«POST/webhooks/ack» - تأكيد (اختياري) للمعالجة اليدوية من DLQ.

9) عقود الخطأ (استجابة المتلقي)

http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
Retry-After: 120
X-Trace-Id: 4e3f...

{
"error": "invalid_state",
"error_description": "payout not found",
"trace_id": "4e3f..."
}

التوصيات: إرجاع رمز واضح دائمًا، وإذا أمكن، «إعادة المحاولة بعد». لا تعيد التفاصيل الأمنية المفصلة.

10) الرصد و SLO

• التسليم p50/p95، معدل النجاح، إعادة/حدث، معدل الانخفاض DLQ، المشاركة 2xx/4xx/5xx، نافذة التأخير حتى 2xx.

• التحقق من معدل الفشل (توقيع/وقت)، معدل الندبة، معالج الكمون p95، 5xx.

• التسليم: ≥ 99. 9٪ من الأحداث تتلقى 2xx <3 c p95 (بعد المحاولة الأولى الناجحة).
• التحقق بالتشفير: التحقق من صحة التوقيع ≤ 2-5 ms p95.
• Dedup: 0 تأثيرات متكررة (نتيجة مرة واحدة بالضبط على مستوى المجال).

11) أمن البيانات وخصوصيتها

لا ترسل PAN/PII في متن الويب ؛ استخدم معرفات ثم اسحب للحصول على تفاصيل مقابل واجهة برمجة التطبيقات المصرح بها.
قناع الحقول الحساسة في جذوع الأشجار ؛ تخزين هيئات الأحداث إلى الحد الأدنى فقط، مع TTL.
قم بتشفير متاجر DLQ وإعادة تشغيلها.

12) الحرث والتوافق

النسخة في 'نسخة' (ظرف) وعبر: '/webhooks/v1/payments'.
والميادين الجديدة اختيارية ؛ الإزالة - فقط بعد فترة «الغروب».
قم بتوثيق التغييرات في سجل التغيير القابل للقراءة آليًا (للفحص التلقائي).

13) حالات الاختبار (قائمة مراجعة UAT)

• إعادة تقديم نفس «الحدث _ معرف» → تأثير واحد و «200» إلى مكرر.
• التوقيع: المفتاح الصحيح، المفتاح غير الصحيح، المفتاح القديم (الدوران)، «X-Timestamp» من النافذة.
• التراجع: يعطي المستلم «429» مع «Retry-After» → وقفة صحيحة.
• الأمر: الأحداث "... «تعال قبل»... أنشأت → المعالجة/الانتظار الصحيحة.
• فشل قاعدة البيانات في المتلقي بين التأثير و «علامة _ رؤية» → ذرية/تكرار.
• DLQ وإعادة التشغيل اليدوي → التسليم الناجح.
• «عاصفة» جماعية (يرسل المزود عبوات) → دون خسارة، لا تخنق الحدود الحرجة.

14) مقتطفات صغيرة

pseudo body = json(event)
canonical = ts + "\n" + "POST" + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
headers = {"X-Timestamp": ts, "X-Event-Id": event.event_id, "X-Signature": "v1="+sig}
POST(url, body, headers)

pseudo assert abs(now - X-Timestamp) <= 300 assert timingSafeEqual(hmac(secret, canonical), sig)

if kv.exists("idemp:"+event_id): return 200

begin tx if kv.exists("idemp:"+event_id): commit; return 200 handle(event.data)        // доменная логика kv.set("idemp:"+event_id, "ok", ttl=259200)
commit return 200

15) الأخطاء المتكررة

لا تفريغ → التأثيرات المتكررة (الردود/المدفوعات المزدوجة).
التوقيع بدون طابع زمني/نافذة → ثغرة إعادة التشغيل.
تخزين سر HMAC واحد على جميع الشركاء.
الردود '200' قبل إصلاح النتيجة → فقدان أحداث الاصطدام.
«غسل» تفاصيل الأمان في الإجابات/السجلات.
عدم وجود DLQ/إعادة التشغيل - الحوادث غير قابلة للحل.

16) ورقة غش التنفيذ

الأمان: HMAC v1 + 'X-Timestamp' + 'X-Event-Id'، نافذة ≤ 5 دقائق ؛ قائمة السماح mTLS/IP حسب الاقتضاء.
Конверт: 'event _ id', 'type', 'version', 'ts', 'tery', 'data'.
التسليم: مرة واحدة على الأقل، التراجع مع jitter، «Retry-After»، DLQ + إعادة تشغيل API.
الخصوصية: KV-cache 24-72 h، تثبيت ذري للتأثير + 'mark _ seen'.
إمكانية الرصد: التسليم والتوقيع والمقاييس المزدوجة ؛ trace _ id.
الوثائق: النسخة، ورموز الاستجابة، والأمثلة، والقائمة المرجعية للغلاف الجوي الموحد.

ملخص السيرة الذاتية

تم بناء خطافات الويب المستمرة على ثلاثة حيتان: مظروف موقع، وتسليم مرة واحدة على الأقل ومعالجة غبية. إضفاء الطابع الرسمي على العقد، وتمكين HMAC/mTLS ونافذة الوقت، وتنفيذ retrai + DLQ وإعادة التشغيل، وتخزين الملصقات الخفية والتقاط التأثيرات ذريًا. ثم تظل الأحداث موثوقة حتى مع فشل الشبكة وقمم التحميل و «تكرارات القدر» النادرة.