تسمح Webhooks في WooCommerce بإرسال إشعار إلى نظام خارجي عند إنشاء طلب أو تحديث منتج أو وقوع حدث مخصص. لكن نجاح حفظ Webhook في لوحة المتجر لا يثبت أن الطرف الآخر استقبل البيانات أو تحقق منها أو نفذها مرة واحدة فقط. يحتاج التكامل إلى سجل تسليم، وتحقق من التوقيع، ومعالجة آمنة للتكرار والفشل.
توضح وثائق WooCommerce أن كل Webhook يملك موضوعًا وعنوان تسليم وسرًا يُستخدم لإنشاء توقيع HMAC-SHA256. تحفظ المنصة أيضًا سجلات للطلب والرد، وقد تعطل Webhook بعد سلسلة من عمليات التسليم الفاشلة. لذلك يجب تصميم المراقبة منذ البداية.
ماذا ترسل Webhooks في WooCommerce؟
يمكن للموضوع أن يكون order.created أو order.updated أو product.updated. يرسل WooCommerce طلب HTTP إلى عنوان التسليم، ويضع رؤوسًا تعرف الموضوع والمورد والحدث ومعرّف Webhook ومعرّف التسليم. يحتوي الرأس X-WC-Webhook-Signature على توقيع مشتق من جسم الطلب والسر المشترك.
اختر موضوعًا ضيقًا قدر الإمكان. إذا كان النظام الخارجي يحتاج الطلب الجديد فقط، فلا تستخدم حدثًا عامًا يطلق عند كل تعديل. قلّل البيانات التي تسجلها، ولا تطبع أسرارًا أو بيانات دفع أو بيانات عميل كاملة في ملف يمكن مشاركته خارج الفريق.
يمكن إعداد التكاملات ضمن خدمة إنشاء متجر WooCommerce، مع إبقاء التحقق والمعالجة الآمنة داخل الخادم المستقبل.
كيف تتحقق من التوقيع قبل المعالجة؟
اقرأ جسم الطلب الخام كما وصل، واحسب HMAC-SHA256 باستخدام السر نفسه، ثم حوّل الناتج إلى Base64 وقارنه بالتوقيع بمقارنة ثابتة الزمن. لا تعِد بناء JSON من كائن محلل قبل الحساب؛ تغيير ترتيب الحقول أو المسافات قد ينتج قيمة مختلفة.
بعد التحقق، افحص نوع الحدث ومعرّف التسليم. التوقيع يثبت أن الجسم يطابق السر، لكنه لا يمنع تكرار طلب صحيح. لذلك احفظ X-WC-Webhook-Delivery-ID أو مفتاحًا مركبًا يضم معرّف الحدث والطلب، وطبّق مبدأ التنفيذ مرة واحدة قبل تحديث المخزون أو إنشاء شحنة.
- استقبل الجسم الخام والرؤوس دون تنفيذ أثر جانبي.
- تحقق من التوقيع والموضوع ومعرّف Webhook والتسليم.
- احجز معرّف التسليم مرة واحدة، ثم نفّذ العملية وسجل نتيجتها.
كيف تقرأ سجلات التسليم؟
توضح وثائق WooCommerce أن سجلات Webhooks تظهر ضمن WooCommerce ثم الحالة ثم السجلات، ويمكن ترشيح مصدر webhooks-delivery. راجع عنوان الطلب والمدة ورمز الاستجابة والرؤوس وجسم الرد، مع إخفاء البيانات الحساسة عند نسخ السجل إلى تذكرة دعم.
الرد 2xx يعني أن الخادم قبل الطلب على مستوى HTTP، لكنه لا يثبت أن كل عملية داخلية اكتملت. اجعل الخادم يرد بعد حفظ المهمة في طابور موثوق، ثم عالجها في الخلفية. إذا أرجع 500 بعد تنفيذ العملية فعلًا، قد تصل محاولة أخرى وتكرر الأثر إن لم يكن المعالج يمنع التكرار.
تشير الوثائق إلى أن إخفاقات متتالية قد تعطل Webhook تلقائيًا. بعد إصلاح الخادم، راجع حالة Webhook وأعد تفعيله فقط بعد التأكد من السبب. واقرأ اختبار توافق WooCommerce مع HPOS قبل تغيير تخزين الطلبات، لأن بعض التكاملات القديمة قد تعتمد بنية لم تعد مناسبة.
مثال افتراضي
مثال افتراضي: متجر يرسل order.updated إلى نظام شحن. استقبل الخادم الحدث وأنشأ شحنة، لكنه انقطع قبل إرجاع 200. وصل الحدث مرة ثانية فأنشأ شحنة أخرى للطلب نفسه. كان التوقيع صحيحًا في المرتين، لكن النظام لم يحفظ معرّف التسليم ولم يفرض مفتاحًا فريدًا للطلب والشحنة.
يحل الفريق المشكلة بحفظ معرّف التسليم، وربط إنشاء الشحنة بمفتاح طلب فريد، وإرجاع 2xx بعد قبول المهمة في الطابور. ثم يراجع السجل للتأكد من توقف الإخفاقات، ويطابق حالة الشحنة مع المزود قبل أي إلغاء.
كيف تعالج الفشل دون إعادة عمياء؟
صنّف الأخطاء إلى مؤقتة ودائمة. انقطاع الشبكة أو 503 قد يسمح بمحاولة مؤجلة، بينما 401 يدل غالبًا على سر أو صلاحية خاطئة، و404 قد يعني أن عنوان التسليم تغير. ضع حدًا للمحاولات مع تباعد زمني، واحفظ آخر خطأ ووقت المحاولة.
لا تُعد إرسال حدث أنشأ أثرًا خارجيًا إذا كانت النتيجة غير مؤكدة؛ استعلم أولًا من النظام الخارجي بواسطة معرّف الطلب. اختبر Webhook بحدث تجريبي لا يسبب شحنة أو رسالة حقيقية، ثم اختبر حدثًا فعليًا محدودًا. راقب زمن الاستجابة، وتحقق من أن السجل لا يكشف السر، وأن تدوير السر يتم على الطرفين في نافذة مخططة.
توضح وثائق REST API الرسمية أن المفاتيح مرتبطة بمستخدم وصلاحيات محددة، وأن السر يظهر مرة واحدة عند إنشائه. لذلك استخدم أقل صلاحية يحتاجها التكامل، ولا تضع مفاتيح REST API مكان سر Webhook بلا سبب موثق.
قائمة مراجعة
- [ ] موضوع Webhook محدد للحدث المطلوب.
- [ ] عنوان التسليم يستخدم HTTPS.
- [ ] السر محفوظ خارج الشفرة والسجلات.
- [ ] التوقيع يُحسب من الجسم الخام ويُقارن بأمان.
- [ ] معرّف التسليم يُحجز لمنع التكرار.
- [ ] المعالجة الثقيلة تعمل في طابور.
- [ ] السجلات تخفي بيانات العميل والأسرار.
- [ ] توجد سياسة للأخطاء المؤقتة والدائمة.
- [ ] تمت مراجعة حالة Webhook بعد الفشل المتكرر.
المصادر الرسمية
بهذا الأسلوب يصبح سجل التسليم أداة تشخيص، ويصبح التوقيع بوابة قبول، بينما يمنع الحجز الفريد تكرار الشحن أو المخزون حتى عند إعادة الإرسال.
المراجع والمصادر
محتوى إرشادي أُعد بمساعدة الذكاء الاصطناعي. الأمثلة افتراضية للتوضيح، وليست نتائج لعملاء تمايز.
تمايز للتسويق وتطوير المتاجر الإلكترونيةتقنية وتسويق
نسمعك