
نظام المحاسبة يريد معرفة كل طلب جديد، وشركة الشحن تريد العنوان، ومنصة الرسائل تريد إرسال التأكيد. بدل أن يسأل كل نظام متجرك كل دقيقة، تجعل Webhooks في ووكومرس المتجر يرسل الحدث فور وقوعه إلى عنوان تحدده. الإعداد بسيط من لوحة ووكومرس، لكن الطرف المستقبل هو ما يحدد هل التكامل آمن ومستقر: يتحقق من التوقيع، ويرد بسرعة، ولا يعالج الحدث نفسه مرتين. نشرح الطرفين بما في كود ووكومرس نفسه.
أهم ما في الموضوع
- كل تسليم يحمل ترويسة X-WC-Webhook-Signature: توقيع HMAC-SHA256 للمحتوى بالسر، مرمّزًا بـ base64.
- ووكومرس يعطّل الـ Webhook تلقائيًا بعد أكثر من 5 إخفاقات متتالية؛ أي رد غير 2xx أو 301 أو 302 يُحسب إخفاقًا.
- سجلات التسليم في ووكومرس ← الحالة ← السجلات، تحت المصدر webhooks-delivery.
إنشاء Webhook في ووكومرس
- 1
افتح الإعدادات المتقدمة
ووكومرس ← الإعدادات ← متقدم ← Webhooks، ثم «إضافة Webhook».
- 2
الاسم والحالة
اسم يوضح الوجهة مثل «طلبات ← المحاسبة»، والحالة «نشط». الحالة «متوقف» تحفظ الإعداد دون إرسال.
- 3
اختر الموضوع
مواضيع جاهزة للطلبات والعملاء والمنتجات والكوبونات (إنشاء وتحديث وحذف واستعادة)، أو «Action» مع اسم خطاف مثل woocommerce_add_to_cart لأحداث مخصصة.
- 4
رابط التسليم والسر
رابط HTTPS للطرف المستقبل، وسر طويل عشوائي. إذا تركت السر فارغًا يستخدم ووكومرس السر الخاص بمستخدم الـ API الحالي، والأفضل سر مستقل لكل Webhook.
- 5
احفظ وراقب الاختبار
عند الحفظ يرسل ووكومرس طلب ping بمحتوى نصي webhook_id=رقم الـ Webhook، وينتظر رد 200 تحديدًا. إذا رد الطرف المستقبل بغيره تظهر رسالة خطأ برمز الاستجابة.
ما الذي يصل إلى الطرف المستقبل؟
| الترويسة | المحتوى | الاستخدام |
|---|---|---|
| X-WC-Webhook-Topic | مثل order.created | توجيه الحدث للمعالج المناسب |
| X-WC-Webhook-Resource / Event | order و created مفصولين | تصفية أدق |
| X-WC-Webhook-Signature | base64 لتوقيع HMAC-SHA256 | رفض الطلبات المزيفة |
| X-WC-Webhook-ID | رقم الـ Webhook | معرفة أي إعداد أرسل |
| X-WC-Webhook-Delivery-ID | معرّف التسليم | الربط بسجل التسليم في ووكومرس |
| X-WC-Webhook-Source | رابط المتجر | إذا كان المستقبل يخدم أكثر من متجر |
والمحتوى نفسه JSON بالشكل الذي يعيده REST API لنفس المورد، أي الطلب كاملًا بأسطره وعنوانه وحالته.
طرف مستقبل يتحقق من التوقيع
التوقيع يُحسب على المحتوى الخام كما وصل، بعد ترميزه JSON. لذلك اقرأ php://input قبل أي تحويل، واحسب التوقيع نفسه وقارنه:
<?php
$raw = file_get_contents( 'php://input' );
$secret = (string) getenv( 'WC_WEBHOOK_SECRET' );
// طلب الاختبار عند الحفظ: محتوى نصي webhook_id=..، ويكفي الرد بـ 200
if ( 0 === strpos( $raw, 'webhook_id=' ) ) {
http_response_code( 200 );
exit;
}
$expected = base64_encode( hash_hmac( 'sha256', $raw, $secret, true ) );
$given = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
if ( '' === $secret || ! hash_equals( $expected, $given ) ) {
http_response_code( 401 );
exit;
}
$topic = $_SERVER['HTTP_X_WC_WEBHOOK_TOPIC'] ?? '';
$order = json_decode( $raw, true );
// احفظ الحدث في طابور، ثم رد فورًا؛ المعالجة الثقيلة تتم لاحقًا
queue_event( $topic, $order['id'] ?? 0, $order['date_modified_gmt'] ?? '', $raw );
http_response_code( 200 );من جهة المتجر: الأداء والسلامة
- التسليم غير متزامن: افتراضيًا يضع ووكومرس التسليم في Action Scheduler تحت مجموعة woocommerce-webhooks، فلا ينتظر العميل في صفحة الدفع رد الطرف الآخر. لكن هذا يعني أن الكرون يجب أن يعمل؛ إذا تكدست المهام المعلقة تتأخر كل الأحداث.
- التعطيل التلقائي: بعد أكثر من خمسة إخفاقات متتالية تتغير حالة الـ Webhook إلى معطّل. راقب ذلك، لأن التكامل يتوقف بصمت. الحد قابل للتغيير بفلتر woocommerce_max_webhook_delivery_failures.
- Webhook غير معروف: كل Webhook يرسل بيانات العملاء إلى خادم خارجي. راجع القائمة دوريًا، فإضافة Webhook خفي من أساليب سرقة بيانات الطلبات في المتاجر المخترقة.
أسئلة عن Webhooks ووكومرس
لماذا توقف الـ Webhook عن الإرسال فجأة؟
هل يعيد ووكومرس إرسال الأحداث الفاشلة؟
Webhook أم استدعاء الـ API من خطاف في الكود؟
مقالات قريبة
المراجع
توثيق Webhooks في ووكومرس، وكود الصنف WC_Webhook في ووكومرس 11.2 (الترويسات وطريقة التوقيع وطلب الاختبار). راجعناهما في 18 أكتوبر 2026.
اربط ووكومرس بنظامك بأمان
نبني لك التكامل بين متجرك وأنظمة المحاسبة أو الشحن أو الرسائل، مع توقيع ومراقبة وخطة لاستدراك الأحداث الفائتة.
اطلب تكاملًا مخصصًا