الانتقال إلى المحتوى الرئيسي
يقلب Webhook اتجاه عملية الربط. فبدلًا من أن تسأل OTO عمّا حدث كل بضع دقائق، تستضيف أنت عنوان URL وتُبلغك OTO بما يحدث.

​
أنواع الأحداث الثلاثة

اشترك في shipmentError حتى لو لم تشترك في أي شيء آخرالحجز الفاشل صامت بطبيعته: الطلب لا يتحرك، ولا يُرسَل أي حدث تغيير حالة لأن شيئًا لم يتغير.أما البيانات المرسلة (Payload) فتذكر السبب: errorCode، ونص رد شركة الشحن في deliveryCompanyResponse، وغالبًا ما يكون شيئًا مثل مدينة أو رمز بريدي ناقص. ومثل هذه المشكلات تُحل في ثوانٍ إذا علم بها أحد، وتبقى غير مرئية لأيام إذا لم يعلم بها أحد.

​
تسجيل Webhook

POST /rest/v2/webhook Starter+ GET يعرض اشتراكاتك، وPUT يحدّث اشتراكًا باستخدام id، وDELETE يحذفه. وجميعها على المسار نفسه.

​
ما الذي يصلك؟

تحتوي بيانات orderStatus على الطلب وحالته الجديدة، وشركة الشحن والسائق إن وُجدا، ورقم التتبع ورابط التتبع، ورابطًا لبوليصة الشحن (AWB)، وtimestamp بتوقيت UTC. وتحتوي بيانات shipmentError على orderId، وerrorCode، وerrorMessage الصادرة من OTO، والرد الخام من شركة الشحن في deliveryCompanyResponse. وتحتوي بيانات newOrders على الطلب كاملًا: العنوان، والمنتجات، والوزن، والمبالغ الإجمالية، وطريقة الدفع، وقناة البيع، والمستودع.

​
التحقق من أن الطلب صادر من OTO

تحمل كل بيانات مرسلة حقل signature: وهو قيمة HMAC-SHA256 محسوبة على سلسلة نصية موصولة بنقطتين رأسيتين، ومرمّزة بـ base64، باستخدام secretKey الذي سجّلته.
تحقق من التوقيع، وارفض الطوابع الزمنية القديمةيستطيع أي شخص يعرف عنوان Webhook الخاص بك الوصول إليه. ودون التحقق، يستطيع أي شخص من هؤلاء أن يُبلغ نظامك بأن طلبًا ما قد تم توصيله.أعد حساب HMAC على السلسلة الموقّعة وقارنه بمقارنة ثابتة الزمن (Constant-time). ثم تأكد من أن الطابع الزمني حديث: فالتوقيع الصحيح على بيانات قديمة هو إعادة إرسال (Replay)، وأخفّ ما قد يفعله هو تعليم طلب الأمس كـ«تم التوصيل» مرة أخرى.

​
بناء نقطة نهاية يُعتمد عليها

  • أجب فورًا. أعد 200 بمجرد استلام البيانات، ونفّذ المعالجة بعد ذلك. فنقطة النهاية البطيئة تبدو كأنها معطلة.
  • توقّع التكرار. قد تتكرر الإرسالات. اعتمد على orderId مع الحالة والطابع الزمني مفتاحًا، واجعل إعادة المعالجة غير ضارة.
  • توقّع وصولها بغير ترتيب. توقيتات الشبكة لا تلتزم بتسلسل الحالات لديك. لا تُعد الطلب إلى حالة سابقة أبدًا لأن حدثًا أقدم وصل متأخرًا.
  • سجّل النص الخام قبل تحليله. عندما يتعطل الربط في الساعة الثانية فجرًا، فإن البيانات التي لم تحتفظ بها هي تحديدًا ما كنت تحتاجه.

​
صفحات ذات صلة