كيف أُعدّ Webhooks لإرسال أحداث الطلبات والجلسات إلى واجهة برمجة التطبيقات أو البريد الإلكتروني؟

ما الذي تفعله Webhooks

الـ Webhook يشترك في حدث معين في المتجر. عند حدوث هذا الحدث، ترسل Storeep فوراً بيانات الحدث إلى عنوان URL تحدده (نوع API) أو إلى عنوان بريد إلكتروني تحدده (نوع البريد الإلكتروني). تُستخدم Webhooks عادةً لدمج تتبع الطلبات، ومزامنة أنظمة إدارة علاقات العملاء، وتحويلات منصات الإعلانات، والإشعارات المؤتمتة.

لإدارة Webhooks، انتقل إلى الإعدادات → Webhooks. تحتاج إلى صلاحية الإعدادات لعرض أو تعديل Webhooks.

حدود Webhook

• الحد الأقصى 20 Webhook لكل متجر. إذا حاولت إضافة Webhook رقم 21 ستظهر رسالة الخطأ "لقد وصلت إلى الحد الأقصى 20 Webhook لكل متجر".
• تظهر القائمة Webhooks الأحدث أولاً، مع تقسيم الصفحات إلى 40 في كل صفحة.

إنشاء Webhook

انقر على إضافة Webhook جديد، ثم املأ الحقول أدناه، ثم انقر إضافة.

تفعيل

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

الاسم

• إجباري. الحد الأقصى 50 حرفاً.
• تسمية وصفية تظهر في القائمة، مثل Facebook CAPI order created.

النوع

• API: ترسل Storeep طلب HTTP POST يحمل بيانات الحدث إلى عنوان URL الخاص بك.
• البريد الإلكتروني: ترسل Storeep بريداً إلكترونياً يحتوي على بيانات الحدث إلى عنوانك.

الحدث

الحدث في المتجر الذي يُطلق Webhook. هناك ثلاثة أحداث:

• تم إنشاء جلسة: تم إنشاء جلسة زائر جديدة في متجرك.
• تم إنشاء طلب: تم وضع طلب جديد.
• تم تحديث طلب: تم تغيير حالة أو بيانات طلب موجود.

هام: نوع البريد الإلكتروني يرسل فقط عند تم إنشاء طلب وتم تحديث طلب. إذا اخترت البريد الإلكتروني مع تم إنشاء جلسة، سيتم حفظ Webhook لكن لن يرسل شيئاً أبداً. استخدم نوع API إذا كنت بحاجة لحدث الجلسة.

التنسيق

هناك خيار واحد فقط، Json: يتم إرسال البيانات كوثيقة JSON.

عنوان URL (لنمط API فقط)

• إجباري عند اختيار نوع API. الحد الأقصى 500 حرف.
• يعرض الحقل بادئة https:// لك، لذا أدخل فقط اسم المضيف والمسار، مثل api.example.com/events/order. إذا قمت بلصق عنوان كامل يبدأ بـ https:// أو http://، سيتم حذف البادئة قبل الحفظ.
• الحقول الديناميكية: يمكنك إدراج أي حقل من بيانات الحدث في عنوان URL باستخدام الصيغة ذات الأقواس المزدوجة {{field_name}}. مثال: example.com/postback?cid={{fbclid}}&payout={{order_total}}. يتم ترميز القيم لعناوين URL، وأي حقل غير موجود يصبح فارغاً. هذا يتيح لك إرسال بيانات التحويل مباشرة إلى منصة إعلانات دون وسيط.
• يتم التحقق من صحة العنوان بعد إزالة الحقول الديناميكية، فإذا كان غير صالح ستظهر رسالة "العنوان الذي أدخلته غير صحيح".

عنوان البريد الإلكتروني (لنمط البريد الإلكتروني فقط)

• إجباري عند اختيار نوع البريد الإلكتروني. يجب أن يكون عنواناً صحيحاً، والحد الأقصى 127 حرفاً.

تعديل Webhook

انقر على أي صف لفتح المحرر. كل الحقول قابلة للتعديل. حقل عنوان URL يظهر فقط إذا كان النوع المحفوظ API، وحقل البريد الإلكتروني يظهر فقط إذا كان النوع المحفوظ البريد الإلكتروني. انقر حفظ للتطبيق. إذا حفظت مع إلغاء تفعيل تفعيل، سيتم تعطيل Webhook دون حذفه.

أعمدة قائمة Webhooks

• الاسم: التسمية مع تاريخ الإنشاء.
• URL / البريد الإلكتروني: الوجهة.
• النوع: API أو البريد الإلكتروني.
• الحدث: تم إنشاء جلسة، تم إنشاء طلب، أو تم تحديث طلب.
• التنسيق: Json.
• الحالة: مفعل أو غير مفعل.

حذف Webhook

حدد صفاً أو أكثر ثم انقر حذف Webhooks. الحذف نهائي ويوقف جميع الإرساليات المستقبلية لهذا الاشتراك.

التسليم، إعادة المحاولة، ورسائل الفشل

ينطبق هذا القسم على Webhooks من نوع API. Webhooks من نوع البريد الإلكتروني تُرسل مرة واحدة فقط دون إعادة محاولة ودون تتبع الفشل.

سلوك إعادة المحاولة

• كل طلب له مهلة 5 ثوانٍ. إذا أعاد الهدف خطأ 5xx، أو 429 (تحديد معدل)، أو لم يكن بالإمكان الوصول إليه (خطأ اتصال)، يعتبر التسليم فشلاً مؤقتاً ويتم إعادة المحاولة.
• بعد فشل التسليم الأول، تعيد Storeep المحاولة بتدرج زمني متزايد حتى 5 مرات: تقريباً بعد 30 ثانية، 60 ثانية، 120 ثانية، 240 ثانية، ثم 480 ثانية. بعد آخر محاولة، يتم تجاهل الحدث.
• استجابة 4xx غير 429 (مثل 404 أو 403) تعتبر فشلاً دائماً. لا تعيد Storeep المحاولة، لأن نقطة النهاية الخاطئة أو الرافضة لن تصلح نفسها تلقائياً.
• إذا كان لديك عدة Webhooks على نفس الحدث، تعيد المحاولة فقط للتي فشلت. النقاط التي نجحت تُتجاهل، فلا تتلقى إرساليات مكررة.

رسالة إخطار الفشل

• تحتسب Storeep عدد الإخفاقات المتتالية لكل Webhook. بعد 5 إخفاقات متتالية، يتلقى مالك المتجر رسالة بريد إلكتروني بعنوان "إجراء مطلوب: Webhook الخاص بك في Storeep يفشل"، بلغة المالك، وتحتوي على اسم Webhook، الوجهة، الحدث، وآخر رمز حالة HTTP.
• تتلقى رسالة واحدة فقط لكل سلسلة إخفاقات. لا تُرسل رسائل أخرى حتى يتعافى Webhook.
• بمجرد نجاح التسليم مجدداً، يتم إعادة تعيين عداد الفشل إلى الصفر ويُعاد تفعيل الإخطار، بحيث يمكن إخطارك في حال حدوث سلسلة إخفاقات جديدة مستقبلاً.

نصائح وملاحظات هامة

• يمكنك إنشاء عدة Webhooks لنفس الحدث، مثلاً إرسال تم إنشاء طلب إلى كل من نظام إدارة علاقات العملاء ومنصة إعلانات كمدخلين منفصلين.
• إذا كانت نقطة النهاية لديك تحتاج مصادقة، ضع رمزاً في سلسلة استعلام العنوان، إما ثابتاً أو عبر {{placeholder}} من بيانات الحدث، أو استخدم وسيطاً يضيف المصادقة قبل التوجيه.
• تم إنشاء جلسة يُطلق لكل جلسة زائر فريدة وقد يكون ذا حجم كبير في المتاجر النشطة. اشترك فيه فقط إذا كانت نقطة النهاية لديك قادرة على التعامل مع هذا الحجم، وتذكر أنه يعمل فقط مع نوع API.