الويب هوك (Webhooks)
يُخطر الويب هوك نظامًا خارجيًا لحظيًا عندما يحدث شيء في متجرك — إنشاء طلب، أو دفعه، أو تجهيزه، أو إلغاؤه، وغير ذلك. فبدل أن يسأل ذلك النظام TakeTheme باستمرار "هل تغيّر شيء؟"، ترسل TakeTheme رسالة فور حدوث التغيير.
استخدمه لإبقاء نظام ERP أو برنامج محاسبة أو مخزن/شركة لوجستيات أو نظام CRM أو لوحة تحكم داخلية متزامنًا مع متجرك تلقائيًا.
تُدار الويب هوك من الإعدادات ← الويب هوك.
الويب هوك متاح في الباقات التي تتضمن وصول المطوّرين. وإذا كانت باقتك لا تشمله، فسيطلب منك تبويب الويب هوك الترقية. راجع باقتك في صفحة الفوترة داخل لوحة التحكم.
إعداد الوي ب هوك يعني توجيه TakeTheme إلى عنوان على خادم تتحكم فيه أنت أو مطوّرك وقادر على استقبال الرسائل والتحقق منها. أما إذا كنت تريد رسائل بريد تلقائية للعملاء (تأكيد الطلب، السلة المتروكة، طلب التقييم) فما تحتاجه هو أتمتة التسويق — بلا برمجة.
صفحة الويب هوك
تمنحك صفحة الإعدادات ← الويب هوك نظرة شاملة على كل عنوان:
- بطاقات الإحصاءات — إجمالي العناوين (من أصل حدّك البالغ 5)، وكم منها نشط أو متعثر أو معطّل.
- البحث والفلاتر — ابحث عن عنوان بالرابط أو الوصف أو الحدث، وصفِّ حسب الكل / النشط / المعطّل.
- بطاقات العناوين — تعرض كل بطاقة رابط الوجهة (مع زر نسخ بضغطة واحدة)، وشارة الحالة، والأحداث المشترَك بها، وتاريخ الإنشاء، وآخر تسليم ناجح، وعدد الإخفاقات إن كان متعثرًا.
شارات الحالة
| الشارة | المعنى |
|---|---|
| نشط | سليم — يستقبل الأحداث ويسلّمها بنجاح. |
| متعثر | ما زال نشطًا لكن آخر عمليات التسليم فشلت. راجعه قبل أن يُعطَّل. |
| معطّل | لا يستقبل الأحداث — إما لأنك أوقفته أو لأن TakeTheme عطّلته تلقائيًا بعد إخفاقات متكررة. |
إنشاء عنوان
- اذهب إلى الإعدادات ← الويب هوك واضغط إنشاء ويب هوك (أعلى اليسار). وإذا بلغت حد الخمسة عناوين، احذف عنوانًا غير مستخدم أولًا.
- املأ النموذج:
- رابط العنوان (مطلوب) — عنوان HTTPS الذي سيستقبل الأحداث، مثل
https://example.com/webhooks/taketheme. تُرفض روابطhttp://العادية، ويجب أن يكون العنوان متاحًا للوصول العام (العناوين الداخلية/الخاصة محظورة). - الأحداث (مطلوب) — اختر الأحداث التي يستقبلها هذا العنوان. حدد حدثًا واحدًا على الأقل.
- الوصف (اختياري) — ملاحظة لفريقك، مثل "مزامنة تجهيز المخزن".
- رابط العنوان (مطلوب) — عنوان HTTPS الذي سيستقبل الأحداث، مثل
- اضغط إنشاء.
احفظ مفتاح التوقيع
فور إنشاء العنوان، تعرض TakeTheme مفتاح توقيع (يبدأ بـ whsec_…). ويستخدمه خادمك المستقبِل للتأكد من أن الرسائل الواردة صادرة فعلًا عن TakeTheme.
يظهر مفتاح التوقيع مرة واحدة عند الإنشاء (ثم عند تدويره فقط). انسخه واحفظه في مكان آمن. وإذا فقدته فستحتاج إلى تدويره للحصول على مفتاح جديد.
الأحداث المتاحة للاشتراك
| الحدث | يُرسَل عندما… |
|---|---|
order.placed | يُنشأ طلب جديد. |
order.paid | يُدفع الطلب / يُحصَّل المبلغ. |
order.fulfilled | يُعلَّم الطلب كمُجهَّز. |
order.cancelled | يُلغى الطلب. |
order.returned | يُعلَّم الطلب كمرتجع. |
order.refunded | يُسترد مبلغ الطلب. |
order.updated | يُعدَّل الطلب أو تُسوَّى حالته. |
اشترك فقط في الأحداث التي يعالجها النظام المستقبِل فعلًا. ولمعرفة البيانات التي يحملها كل حدث، راجع مرجع الأحداث.
إدارة العنوان
تحتوي كل بطاقة عنوان على هذه الإجراءات:
| الإجراء | الوظيفة |
|---|---|
| عرض السجلات | فتح سجل التسليم (انظر أدناه). |
| تعديل | تغيير الرابط أو الأحداث المشترَك بها أو الوصف، وتفعيل العنوان أو تعطيله. |
| تدوير المفتاح | إنشاء مفتاح توقيع جديد. ويتوقف القديم فورًا — حدّث خادمك سريعًا. |
| تفعيل / تعطيل | إيقاف التسليم أو استئنافه دون حذف العنوان. |
| حذف | إزالة العنوان نهائيًا. |
سجلات التسليم
اضغط عرض السجلات على أي عنوان لرؤية محاولات التسليم الأخيرة. ويعرض كل صف:
- الحدث — الحدث المُرسَل (مثل
order.paid). - الحالة —
successأوfailedأوpendingأوexhausted. - المحاولة — رقم المحاولة (مثل
3 / 8). - HTTP — رمز الحالة الذي أعاده خادمك (
—عند انتهاء المهلة أو خطأ الاتصال). - الوقت — وقت المحاولة.
وسّع أي صف لرؤية رسالة الخطأ ورد خادمك والبيانات المُرسَلة بالضبط — وهي معلومات ثمينة عند تتبّع سبب فشل التسليم.
استخدم تحديث لإعادة التحميل، وإعادة إرسال المستنفدة لإرسال كل عملية فشلت نهائيًا (يعرض الزر عددها). عالج المشكلة في خادمك أولًا ثم أعد الإرسال.
تُحفظ سجلات التسليم لفترة محدودة، والغرض منها المعالجة القريبة لا التدقيق طويل المدى.
عند فشل التسليم
تتوقع TakeTheme أن يردّ عنوانك باستجابة ناجحة خلال نحو 10 ثوانٍ. وإذا لم يفعل (خادم متوقف أو خطأ أو بطء)، فإنها تعيد المحاولة تلقائيًا بفواصل متزايدة — حتى 8 محاولات موزّعة على يوم تقريبًا.
وإذا استمر العنوان في الفشل (استنفدت ثلاث عمليات تسليم كل محاولاتها خلال أسبوع)، تعطّله TakeTheme تلقائيًا لتجنّب إرهاق خادم معطّل، وترسل لك بريدًا لإعلامك. وبعد معالجة المشكلة:
- عدّل العنوان وأعد تفعيله (أو استخدم تفعيل).
- افتح عرض السجلات واضغط إعادة إرسال المستنفدة لإرسال ما فات.
ولمعرفة جدول إعادة المحاولة الكامل والتفاصيل التقنية للتعطيل التلقائي، راجع التسليم وإعادة المحاولة والإدارة.
لمطوّرك
الجانب المستقبِل مهمة برمجية. أرشد مطوّرك إلى دليل الـ API:
- نظرة عامة على الويب هوك — كيف يعمل التسليم وبداية سريعة للمستقبِل.
- التحقق من التواقيع — التأكد من الأصالة (بأمثلة Node وPython وPHP وRuby وGo).
- مرجع الأحداث — بيانات كل حدث.
- التسليم وإعادة المحاولة والإدارة — الترويسات وإعادة المحاولة والسجلات وواجهة الإدارة.
وكل ما في هذه الصفحة يمكن تنفيذه برمجيًا عبر واجهة الإدارة تحت https://api.taketheme.com/api/v1/store/webhooks — راجع التسليم والإدارة.
أسئلة شائعة
كم عنوانًا يمكنني إنشاؤه؟ حتى 5 لكل متجر. احذف غير المستخدم لإفساح المجال.
عنواني يظهر "متعثر" — ماذ ا أفعل؟ فشلت عمليات التسليم الأخيرة. افتح عرض السجلات، ووسّع صفًا فاشلًا لقراءة الخطأ ورد خادمك، ثم عالج المشكلة قبل التعطيل التلقائي.
فقدت مفتاح التوقيع. هل يمكنني رؤيته مجددًا؟ لا — يُعرض مرة واحدة فقط. اضغط تدوير المفتاح لإنشاء مفتاح جديد ثم حدّثه في خادمك.
هل يرسل الويب هوك رسائل بريد للعملاء؟ لا. الويب هوك يرسل بيانات إلى نظام آخر. وللرسائل التلقائية للعملاء استخدم أتمتة التسويق.
هل يمكن أن يصل الحدث نفسه مرتين؟ أحيانًا نعم — مثلًا إذا تأخر خادمك في الرد فأعادت TakeTheme المحاولة. وينبغي لمطوّرك جعل المستقبِل يتعامل مع التكرار بأمان (بإسقاط المكرر اعتمادًا على معرّف التسليم).