الحدث
سجل بتغير دفعة أو جلسة لعب أو تحقق KYC أو مكافأة أو ملف لاعب أو كائن آخر.
الوثائق / Webhooks
Webhooks وتسليم الأحداث
اضبط نقل الحالات والأحداث بشكل موثوق بين الأنظمة: من إنشاء الرسالة والتحقق من التوقيع إلى تأكيد الاستلام وإعادة التسليم ومراقبة الأخطاء.
الأحداث
الحالات والتغييرات
التوقيع
التحقق من الأصالة
إعادة المحاولات
إعادة التسليم
المراقبة
السجل والتشخيص
مسار الحدث
من الإنشاء إلى التأكيد
01
إنشاء حدث
حدد المعرف والنوع والوقت والكائن والحالة والبيانات المرتبطة.
02
توقيع وإرسال
أرسل الحدث عبر HTTPS مع توقيع ومهلة انتظار محدودة.
03
تأكيد الاستلام
بعد التحقق، احفظ الحدث وأعد بسرعة استجابة HTTP ناجحة.
04
إعادة المحاولة عند الخطأ
أعد التسليم مع زيادة الفاصل واحتفظ بالأحداث غير المرسلة للتحليل.
نظرة عامة
Webhook يبلغ عن تغير الحالة
قد يعيد المرسل التسليم، لذلك يجب على المستلم التحقق من المصدر وتأكيد الاستلام وتطبيق كل حدث مرة واحدة فقط.
التأكيد
يعيد المستلم استجابة HTTP ناجحة بعد التحقق من الحدث وحفظه بشكل موثوق.
الاستعادة
تساعد إعادة الإرسال والتسوية في استعادة البيانات بعد عدم توفر مؤقت لأحد الأنظمة.
مكونات الحدث
ما البيانات التي يجب أن يتضمنها الحدث
تسهل بنية الرسالة الموحدة التحقق والتوجيه والحماية من التكرار ودعم أنواع مختلفة من الأحداث.
معرف الحدث
قيمة فريدة تتعرف بها المنظومة على إعادة التسليم وتجد سجل المعالجة.
نوع الحدث
اسم واضح وثابت يحدد التغيير الذي حدث وطريقة معالجته.
وقت الإنشاء
تاريخ ووقت إنشاء الحدث بالصيغة والمنطقة الزمنية المتفق عليهما.
الكائن المرتبط
نوع ومعرف الدفع أو اللاعب أو الجولة أو الطلب أو المكافأة أو كائن آخر.
إصدار البنية
يساعد رقم الإصدار في تغيير بنية الرسالة بأمان دون تعطيل التكاملات القائمة.
الارتباط بالعملية
معرف الطلب الأصلي أو المعاملة أو الجلسة أو سلسلة الإجراءات المرتبطة.
السياق
العلامة التجارية والمشروع والسوق والبيئة والمزود وغيرها من البيانات اللازمة للتوجيه الصحيح.
بيانات الحدث
الحد الأدنى من الحقول لمعالجة التغيير أو إجراء طلب لاحق إلى API.
التوقيع والتحقق
التحقق من أصالة الحدث وسلامته
قبل تغيير البيانات، يتحقق المستلم من الاتصال الآمن والتوقيع ووقت الإنشاء والمعرف الفريد للحدث.
01
الحصول على الرسالة الأصلية
تحقق من التوقيع باستخدام المحتوى الأصلي للطلب قبل تغيير صيغة JSON.
02
التحقق من الوقت
ارفض الطلب إذا كان وقت الحدث خارج النطاق المسموح.
03
التحقق من التوقيع
استخدم السر والخوارزمية المتفق عليهما لـ HMAC أو التوقيع الرقمي.
04
التحقق من المعرف
تأكد من أن الحدث لم يُطبق من قبل واحفظ نتيجة التحقق.
التسليم وإعادة المحاولات
استجابات HTTP وإعادة التسليم
يجب أن يميز المرسل بين الاستلام الناجح والخطأ المؤقت والرفض الدائم، وعلى المستلم أن يرد بسرعة وبوضوح.
استجابة HTTP ناجحة
تؤكد أن الحدث تم التحقق منه وحفظه بشكل موثوق للمعالجة اللاحقة.
مهلة محدودة
لا تنفذ معالجة طويلة قبل الرد على المرسل — احفظ الحدث أولًا.
إعادة الإرسال
أعد التسليم عند خطأ شبكي مؤقت أو عدم التوفر أو غياب الاستجابة.
زيادة الفاصل
زد فترة الانتظار تدريجيًا بين المحاولات حتى لا تولد حملًا إضافيًا.
طابور الأحداث غير المرسلة
بعد استنفاد المحاولات، احتفظ بالحدث للتشخيص والمعالجة اليدوية.
إعادة الإرسال اليدوية
يمكن للمشغل إعادة إرسال الحدث المحدد دون إنشاء عملية جديدة.
مراقبة التسليم
تتبع عدد المحاولات والاستجابات وآخر خطأ ووقت الإرسال التالي.
الإشعارات
أخطر الفريق بارتفاع الأخطاء واستنفاد المحاولات وتراكم الأحداث في الطابور.
معالجة الأحداث
الحماية من التكرار وترتيب الحالات
يجب ألا يعتمد المستلم على تسليم واحد أو ترتيب صارم للأحداث.
تطبيق مرة واحدة
احفظ معرف الحدث قبل تغيير البيانات.
أكد الحدث المكرر دون خصم أو إضافة أو تغيير مكرر.
اربط الحدث بالكائن وحالته الحالية.
احفظ الحدث وتغيير الأعمال كعملية واحدة متسقة.
الترتيب والحداثة
قارن الوقت أو رقم التسلسل أو إصدار الحدث.
لا تعد الكائن إلى حالة قديمة بسبب تسليم متأخر.
اسمح فقط بانتقالات الحالة المسموحة.
عند الشك، اطلب الحالة الحالية للكائن عبر API.
الاختبار
ما يجب التحقق منه قبل الإطلاق
اختبر التسليم الناجح والتوقيع غير الصحيح والتكرار والاستجابة البطيئة وتغير ترتيب الأحداث والاستعادة بعد العطل.
توقيع غير صحيح
رسالة معدلة أو مفتاح غير معروف أو وقت منتهي أو خوارزمية غير مدعومة.
إعادة التسليم
يصل الحدث نفسه عدة مرات قبل وبعد اكتمال المعالجة.
استجابة بطيئة
يستغرق المستلم وقتًا طويلًا في الرد أو ينقطع الاتصال أو لا يصل التأكيد إلى المرسل.
اختلال الترتيب
تصل الحالة النهائية قبل الوسيطة، ويصل الحدث القديم بعد الحدث الجديد.
عنوان غير متاح
تحقق من أخطاء HTTP 5xx وDNS وTLS وحدود المعدل واستنفاد جميع المحاولات.
سجل التسليم
يجب أن يعرض معرف الحدث جميع المحاولات والاستجابات والأخطاء ونتيجة الإرسال اليدوي.
قائمة تحقق قبل الإطلاق
يُفعّل التسليم الفعلي بعد التحقق من الأمان والحماية من التكرار وإعادة الإرسال ومراقبة الأخطاء.
تُستخدم عناوين وأسرار توقيع مختلفة لبيئتي الاختبار والعمل.
يتم التحقق من التوقيع باستخدام الرسالة الأصلية مع مراعاة وقت الإنشاء.
يتم حفظ معرف الحدث ويحمي العمليات من التنفيذ المكرر.
يعيد المستلم بسرعة استجابة HTTP ناجحة بعد حفظ الحدث.
تم إعداد إعادة المحاولات وزيادة الفاصل والإرسال اليدوي.
سجل التسليم والبحث حسب المعرف متاحان لفريق الدعم.
هل تحتاج إلى إعداد تسليم موثوق للأحداث؟
أرسل قائمة الأحداث وعناوين الاستقبال وقواعد تغيير الحالات. سيساعد APIACE في تحديد بنية الرسائل والتحقق من التوقيع وإعادة التسليم ومراقبة الأخطاء.