الحالة والنطاق
هذا إرشاد هندسي عام لتقييم تكامل مستقبلي. عقد webhooks في Anti Sandbox V4 مرتبط بالإصدار المعتمد. لا نحدّد هنا أسماء الترويسات أو خوارزمية التوقيع أو حقول البيانات أو حدود الوقت. احصل على عقد الإصدار المنشور قبل تنفيذ المستقبل.
الوارد والأحداث الصادرة وظيفتان مختلفتان
يستقبل صندوق webhook الوارد رسائل داخل المحادثة، بينما يُبلغ webhook الأحداث الصادر خدمتك بالتغييرات. يحتاج كل اتجاه إلى قواعد مصادقة وتحقق وإعادة محاولة خاصة به. لا تفترض أن بيانات الاعتماد والمخططات قابلة للتبادل.
تحقق من الطلب الأصلي
احفظ بايتات الطلب الخام قبل تحليل JSON. تحقّق من التوقيع وفق العقد الموثّق وبالسر الصحيح للاتصال. إذا تضمن العقد طابعاً زمنياً، تحقّق من صحته وحداثته وفق الحد الموثّق. اتبع طريقة المقارنة ثابتة الزمن المحددة في العقد. لا تسجّل الأسرار ولا تقبل طلباً فشل التحقق منه.
امنع إعادة التشغيل والمعالجة المكررة
المصادقة لا تمنع وصول حدث صحيح أكثر من مرة. استخدم هوية الحدث ونطاق الاتصال الموثّقين لحفظ حالة المعالجة بشكل متين. الحدث المكرر هو العمل نفسه، وليس إذناً بإرسال رد ثانٍ للعميل. نسّق منع التكرار مع استعادة العمل بعد تعطل الخدمة.
احفظ الحدث قبل المعالجة
تحقّق من الحدث المقبول واحفظه قبل تأكيد الاستلام وفق عقد المزوّد. نفّذ عمل الوكيل البطيء خارج مسار الطلب. تتبّع القبول والمعالجة والفشل والاكتمال. أعد محاولة الأخطاء المؤقتة بانتظار متدرج وحدود واضحة؛ الطلب غير الصحيح أو غير المصرّح به يحتاج تحقيقاً لا حلقة محاولات مستمرة.
احفظ ملكية الموظف ودليل التسليم
يجب ألا تعيد المحاولة تفعيل رد الوكيل بعد استلام موظف للمحادثة. أعد التحقق من الملكية قبل الإرسال. احتفظ بسجلات تربط الحدث بمحاولة الرد ونتيجة التسليم من المزوّد مع تقليل المحتوى الحساس. اختبر التكرار والطلب القديم والتوقيع غير الصحيح والتعطل بعد القبول وتسليم المحادثة لموظف قبل الإطلاق.