استقبل خطاف الويب مرة واحدة في نظام أعمالك
تستخدم أحداث الإرجاع اشتراكات منصة المطورين وسر توقيعها. أما استدعاءات تأكيد العنوان فيمكن أن يكون لها سر توقيع خاص بكل طلب. لا تخلط بين السرّين. اشترك في أنواع الأحداث الدقيقة المتاحة في لوحة المطورين؛ ولا تفترض دعم الاشتراك باستخدام أحرف البدل.
تحقّق قبل التحليل
ترسل Alkax X-Alkax-Event-Id وX-Alkax-Timestamp (ثواني Unix) وX-Alkax-Signature (v1= متبوعة بـ HMAC-SHA256 سداسي عشري بأحرف صغيرة). المدخل الموقّع هو الطابع الزمني بترميز UTF-8 ثم نقطة ثم بايتات جسم الطلب الخام نفسها تمامًا. استخدم سلسلة سر التوقيع كمفتاح HMAC. لا تفك ترميزها من base64 ولا تُعِد تسلسل JSON أول ًا. ارفض الطوابع القديمة باستخدام نافذة حداثة من خمس دقائق، والطوابع المستقبلية خارجها، والتوقيعات غير السليمة، وعدم تطابق معرّفات الأحداث بين المغلف والترويسة. حافظ على مزامنة الساعات واستخدم مقارنة بزمن ثابت.
أتِح نقطة الاستقبال عبر نقطة نهاية HTTPS عامة. لا ترسل Alkax إلى وجهات الحلقة المحلية أو الخاصة أو الروابط المحلية أو الوجهات التي يحلّها DNS إلى عناوين خاصة، ولا تتبع إعادة التوجيه. أبقِ أسرار التوقيع خارج الشفرة المصدرية والسجلات والإعدادات العامة.
تنبيهات أطر العمل: يجب أن يلتقط Express الجسم باستخدام express.raw() قبل وسيط JSON؛ ويجب أن يخزّن ASP.NET جسم الطلب غير المعدّل مؤقتًا ويقرأه قبل تحويل النموذج؛ وينبغي أن يستخدم Flask request.get_data() قبل التحليل؛ ويجب ألا تعيد الخوادم الوكيلة كتابة بايتات الجسم. مرّر ترويسات Alkax الثلاث كلها. لا تتحقّق أبدًا من حمولة أعيد تنسيقها للعرض.
القبول المستديم والتكرارات
تحقّق أولًا. في معاملة قاعدة بيانات واحدة، أدخل هوية فريدة تجمع البيئة والحدث مع تجز ئة الجسم الخام، ثم سجّل إجراء الأعمال أو أضف عملًا مستديمًا إلى قائمة انتظار. ثبّت المعاملة قبل إعادة 2xx. يؤدي الانهيار بعد التثبيت وقبل الاستجابة إلى تكرار؛ أعد 2xx دون تكرار الإجراء فقط إذا كانت التجزئة مطابقة. تمثل هوية الحدث نفسها مع تجزئة مختلفة إخفاقًا في سلامة البيانات ويجب ألا تنتج أي آثار. اجلب الحالة المرجعية الحالية بمفتاح بيئتك قبل اتخاذ قرارات حساسة للترتيب. ترتيب التسليم غير مضمون. احتفظ بسجلات إزالة التكرار على الأقل طوال مدة إعادة التشغيل المدعومة لديك.
لا تستدعِ خدمة خارجية لاسترداد الأموال داخل حلقة إعادة محاولة غير محمية. استخدم صندوق صادر معاملاتيًا وعقد عدم تكرار أثر خاصين بك. يعني return.received في Alkax الاستلام المادي، لا تفويض استرداد المال.
سياسة التسليم
يستخدم مُرسِلا خطافات الويب الحديثان مهلة قدرها عشر ثوانٍ وحتى ثماني محاولات تلقائية. تستخدم اشتراكات المشروع فترات إعادة قدرها 2 و4 و8 و16 و32 و64 و128 دقيقة. أما الاستدعاءات الخاصة بكل تأكيد فتستخدم نحو 1 و2 و4 و8 و16 و32 و64 دقيقة، مع تفاوت عشوائي. تخص هذه الجداول مُرسِلين مختلفين. استجابات 4xx غير الناجحة نهائية عدا 408 و425 و429؛ وتُعاد المحاولة عند 5xx وإخفاق النقل. أعد 503 لإخفاق مؤقت في التخزين و2xx للتكرارات المقبولة بصورة مستديمة. لا تُعد 200 قبل نجاح التخزين. تحتاج أخطاء التوقيع الدائمة إلى إصلاح السر أو معالجة الجسم قبل إعادة التشغيل، لا إلى تكرار التسليم عشوائيًا.
في لوحة المطورين، افحص سجل تسليم الاشتراك وصحّح السبب واختر إعادة التشغيل (Replay). تحافظ الإعادة على معرّف الحدث والحمولة، لكنها توقّع بطابع زمني جديد. لذا يجب أن تعتمد إزالة التكرار على معرّف الحدث، لا على التوقيع أو الطابع الزمني.
احفظ أسرار الاشتراك في مدير أسرار. لا يدوّر تدوير بيانات الاعتماد أسرار خطافات الويب. لاستبدال سر اشتراك، أنشئ اشتراكًا بديلًا واقبل السرّين أثناء الانتقال ثم أوقف الاشتراك القديم ووفّق عمليات التسليم المعلّقة.
معالجة الحمولة
يتضمن مغلف المرتجع eventId وtype وoccurredAt وdata. تحتوي البيانات على معرّفات المرتجع والشحنة الأصلية ورقم التتبّع وحالة التفويض واللوجستيات والسبب والنوع ووقت الحدث. تعامل مع merchantReference كبيانات يقدّمها التاجر وقد تكون حساسة. لا تسجّل المغلف بالكامل. لا يحتوي حدث التكامل العام هذا على صلاحيات وصول المستلم أو عناوين دقيقة أو صور أدلة.
Alkax -> signed HTTPS webhook -> verify raw bytes -> durable inbox/work -> 2xx
|
+-> transient failure -> safe retry
عقود التأكيد والاسترداد
تستخدم واجهة HTTP للتأكيد والاستدعاءات السابقة لكل تأكيد والاستدعاءات ذات الإصدارات لكل تأكيد واشتراكات المشروع العامة مخططات مختلفة:
| القناة | الحقول والحالة |
|---|---|
| استجابة HTTP موثّقة للتأكيد | حقول camelCase وحالة نصية؛ لقطة خاصة وdeliveryInstructions؛ حقول الاستخدام الواحد بقيمة null في القراءات العادية |
الاستدعاء الافتراضي لكل تأكيد v1 | حقول المستوى الأعلى eventId وtype وoccurredAt وrequest؛ حقول متداخلة PascalCase وحالة رقمية |
الاستدعاء لكل تأكيد v2 عند اختياره صراحةً | حقول المستوى الأعلى schemaVersion وeventId وtype وoccurredAt وrequest؛ معرّف الطلب ومرجعه وحالته النصية ووقت انتهائه فقط بصيغة camelCase |
| اشتراك المشروع | حقول المستوى الأعلى eventId وtype وoccurredAt وdata؛ بيانات التأكيد تقتصر على id وstatus الرقمي وexpiresAt |
تشير v1= في ترويسة التوقيع إلى آلية HMAC؛ ولا تختار مخطط JSON. اختر الحقل الاختياري callbackSchemaVersion عند إنشاء تأكيد جديد. تبقى بايتات الحدث الموجود في قائمة الانتظار والمخطط المختار دون تغيير عند إعادة التشغيل. تحتفظ إعادة التشغيل اليدوية لكل تأكيد بإجمالي عدد المحاولات؛ ولا تضمن ميزانية جديدة من ثماني محاولات.
للاسترداد عند فقدان الاستجابة، أنشئ callbackSigningSecret اختياريًا وشفّره في تخزين دائم قبل إنشاء التأكيد. يجب أن يتكون من 64 محرفًا سداسيًا عشريًا بأحرف صغيرة مولّدة من 32 بايت عشوائيًا، مع إعداد callbackUrl. تستخدم HMAC نص السر بترميز UTF-8. لا تعيد Alkax أبدًا السر الذي يقدّمه المستدعي. عند حذفه، تنشئ Alkax سرًا باسم webhookSigningSecret وتعيده في استجابة الإنشاء الأولى فقط. لا توجد نقطة نهاية لتدوير السر أو توفيره مجددًا.
تعيد محاولة الإنشاء المتطابقة الطلب الأصلي، مع recipientUrl وحقول السر ذات الاستخدام الواحد بقيمة null، حتى بعد انتهاء صلاحية الرابط الأصلي. احتفظ بالحمولة والمفتاح نفسيهما تمامًا واستخدم مرجعًا مبهمًا جديدًا لمحاولة جديدة. تحقّق من تطابق هوية الحدث بين الترويسة والجسم، واربطه بالمحاولة المحلية الحالية، واحفظ البيئة ومعرّف الحدث مع تجزئة الجسم، ثم وفّق الحالة عبر طلب GET مرجعي موثّق. لا يُبطل انتهاء الرابط اللقطات المكتملة؛ وتقع مسؤولية انتهاء الموافقة والإفصاح على التطبيق المستهلك.
لا تعرض استجابات اختبار تسليم المشروع وسجله إلا بيانات التسليم الوصفية المسموح بها صراحةً. تُستبعد الحمولات الخام ومقتطفات استجابة نقطة الاستقبال وأسباب الإخفاق النصية الحرة لكل أدوار المشروع. تُوقَف أحداث تأكيد المشروع التاريخية غير الآمنة قبل إرسالها ويُرفض تشغيلها يدويًا؛ وتظل الأسرار التاريخية المحتفظ بها بحاجة إلى معالجة تشغيلية محددة النطاق. لا يؤدي ذلك إلى تدوير روابط الوصول أو الأسرار الت ي كُشفت سابقًا.
تُسجَّل إشعارات التأكيد في Sandbox في مخزن اختبار بدلًا من إرسالها إلى صناديق المستلمين الحقيقيين، وتُقيَّد جميع عمليات التأكيد بالمشروع والبيئة. انشر إصدار المزوّد المتوافق قبل استخدام هذه الإضافات. راجع عقد الاستدعاء القابل للاسترداد للاطلاع على مثال الحمولة الدقيق وشروط الإصدار المتبقية. تظل واجهة VolXpr الخاصة المستضافة ومسار التفويض المستديم والعمل الكامل على تزامن دورة الحياة مهام منفصلة.