Webhooks في ووكومرس هي طلبات HTTP POST تلقائية يرسلها ووكومرس إلى رابط تختاره كلما وقع حدث محدد، مثل إنشاء طلب أو تحديث منتج أو حذف عميل. يحمل الطلب البيانات بصيغة JSON وترويسة توقيع تتحقق منها بمفتاح سري مشترك. وهي أبسط طريقة لربط المتجر بالأنظمة الأخرى لحظيا.
أستخدمها لربط المتاجر بأنظمة المحاسبة والشحن وCRM ومنصات الأتمتة. وهذا الدليل جزء من سلسلة الذكاء الاصطناعي والأتمتة.
كيف تعمل Webhooks في ووكومرس؟
عند وقوع الحدث يجهز ووكومرس بيانات المورد بصيغة JSON (مثل الطلب كاملا) ويضعها في طابور الإرسال إلى رابطك. تتم المعالجة في الخلفية عبر Action Scheduler افتراضيا. ويرد الخادم المستقبل برمز 2xx للتأكيد، وأي رد آخر يحسب فشلا.
كيف تنشئ webhook
- اذهب إلى ووكومرس ← الإعدادات ← متقدم ← Webhooks.
- اضغط إضافة webhook.
- املأ الحقول:
- الاسم: اسم وصفي مثل “الطلبات إلى المحاسبة”.
- الحالة: نشط.
- الحدث Topic: الحدث المطلوب (انظر بالأسفل).
- رابط الاستلام: رابط HTTPS الخاص بك.
- المفتاح السري: نص عشوائي طويل يستخدم لتوقيع البيانات.
- إصدار API: إصدار REST API المستخدم في بناء البيانات.
- احفظ، وسيرسل ووكومرس طلب ping للرابط.
الأحداث المتاحة
تغطي الأحداث المدمجة الموارد والإجراءات الأساسية:
| المورد | الأحداث |
|---|---|
| الطلب | order.created, order.updated, order.deleted, order.restored |
| المنتج | product.created, product.updated, product.deleted, product.restored |
| العميل | customer.created, customer.updated, customer.deleted |
| الكوبون | coupon.created, coupon.updated, coupon.deleted, coupon.restored |
يوجد أيضا حدث Action الذي ينطلق مع أي hook في ووردبريس تحدده، ويمكن للمطورين تسجيل أحداث مخصصة.
انتبه إلى أن order.updated ينطلق مع تغييرات كثيرة منها تغيير الحالة والملاحظات. إذا كان يهمك الطلبات المدفوعة فقط فقم بالتصفية حسب الحالة في جهة الاستلام، أو استخدم حدثا مخصصا.
التحقق من التوقيع
يحمل كل إرسال ترويسات مثل X-WC-Webhook-Topic وX-WC-Webhook-Resource وX-WC-Webhook-Delivery-ID وX-WC-Webhook-Signature. والتوقيع هو تجزئة HMAC-SHA256 لجسم الطلب الخام بمفتاحك السري، مشفرة بصيغة base64.
مستقبل بلغة PHP:
$raw = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
$expected = base64_encode( hash_hmac( 'sha256', $raw, getenv( 'WC_WEBHOOK_SECRET' ), true ) );
if ( ! hash_equals( $expected, $signature ) ) {
http_response_code( 401 );
exit;
}
$order = json_decode( $raw, true );
// Queue the work, respond fast.
http_response_code( 200 );
مستقبل Node.js (Express):
app.post('/wc-hook', express.raw({ type: 'application/json' }), (req, res) => {
const expected = crypto.createHmac('sha256', process.env.WC_WEBHOOK_SECRET)
.update(req.body).digest('base64');
const given = req.get('X-WC-Webhook-Signature') || '';
if (given.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
return res.sendStatus(401);
}
res.sendStatus(200);
// process JSON.parse(req.body) asynchronously
});
احسب التجزئة دائما على الجسم الخام قبل أي تحليل JSON يغير المسافات.
تصميم مستقبل موثوق
- رد بسرعة. أرجع 200 وعالج العمل في طابور، فالرد البطيء يسبب انتهاء المهلة والفشل.
- تجنب التكرار. قد يصل نفس الحدث أكثر من مرة، فخزن معرف الإرسال أو رقم الطلب مع الحالة وتجاهل المكرر.
- لا تعتمد على ترتيب الوصول. قد يصل التحديث قبل الإنشاء في حالات نادرة، فاجلب أحدث حالة من REST API إذا كان الترتيب مهما.
- سجل كل شيء لفترة: الترويسات والحالة ونتيجة المعالجة.
حل مشكلة عدم إرسال Webhooks
1. راجع حالة الـ webhook
إذا تكرر فشل الإرسال يعطل ووكومرس الـ webhook بعد مرات فشل متتالية (خمس افتراضيا). أصلح رابط الاستلام ثم أعد الحالة إلى نشط.
2. راجع Action Scheduler
اذهب إلى أدوات ← الإجراءات المجدولة وابحث عن woocommerce_deliver_webhook_async. الإجراءات المعلقة التي لا تنفذ تعني غالبا أن WP-Cron لا يعمل، راجع دليلي عن WP-Cron.
3. راجع السجلات
يسجل ووكومرس عمليات الإرسال في ووكومرس ← الحالة ← السجلات، فابحث عن رمز الرد ومحتواه من رابطك.
4. راجع الخادم المستقبل
- جدار حماية أو حماية من البوتات تحجب طلبات ووكومرس.
- مصادقة Basic Auth على الرابط.
- مشكلات في شهادة TLS.
- الرابط يرجع تحويلا (مثل http إلى https) بدلا من 200.
5. راجع جهة المتجر
- إضافات أمان تحجب الطلبات الصادرة.
- استضافة تقيد اتصالات HTTP الخارجية.
- الحدث لا يقع فعلا (مثل إنشاء طلبات بطريقة تتجاوز الـ hooks).
الاختبار
استخدم خدمة مؤقتة لفحص الطلبات على نسخة الاختبار لرؤية البيانات الحقيقية، ثم وجه الإرسال لرابطك. أنشئ طلبات تجريبية بكل وسيلة دفع. ومع WP-CLI يمكنك عرض الـ webhooks وفحصها:
wp wc webhook list --user=admin
المزيد في دليل أوامر WP-CLI.
قائمة الأمان
- رابط استلام HTTPS فقط
- مفتاح سري طويل عشوائي محفوظ في متغيرات البيئة لا في الكود
- التحقق من التوقيع بمقارنة ثابتة الزمن
- الرابط ينفذ أقل عمل ممكن ويرفض الأحداث غير المتوقعة
- التعامل مع البيانات الشخصية وفق قواعد الخصوصية
أخطاء شائعة
- معالجة ثقيلة قبل الرد تسبب انتهاء المهلة.
- تحليل JSON قبل التحقق من التوقيع.
- استخدام
order.createdلتجهيز الطلب بينما قد يكون غير مدفوع بعد. - نسيان أن webhooks نسخة الاختبار ما زالت موجهة لأنظمة الإنتاج.
تحتاج ربط متجرك بالمحاسبة أو الشحن أو CRM؟ تواصل معي. ولإشعارات الدفع راجع بوابات الدفع في مصر.
الأسئلة الشائعة
ما هو webhook ووكومرس؟
إشعار تلقائي يرسله ووكومرس إلى رابط خارجي عند وقوع حدث في المتجر، مثل إنشاء طلب أو تحديث منتج، ويحمل البيانات المرتبطة بصيغة JSON.
ما الفرق بين Webhooks وREST API؟
REST API سحب: نظامك يطلب البيانات من ووكومرس. أما Webhooks فدفع: ووكومرس يخبر نظامك عند حدوث تغيير. وكثير من الربطات تستخدم الاثنين.
لماذا تم تعطيل webhook ووكومرس؟
يعطل ووكومرس الـ webhook بعد عدد من مرات الفشل المتتالية (خمس مرات افتراضيا). أصلح رابط الاستلام ثم أعد حالته إلى نشط.
هل يمكن إضافة أحداث مخصصة؟
نعم، يمكن للمطورين تسجيل أحداث مخصصة عبر الفلاتر، أو استخدام حدث Action لإطلاق webhook على أي hook في ووردبريس.
