Webhook

تتيح لك Webhooks إرسال بيانات الرحلة إلى خدمات خارجية مثل التحليلات وأنظمة CRM وأدوات التسويق. يمكنك:

إخطار الأنظمة الخارجية عندما يتخذ العميل إجراءً في الرحلة
إرسال بيانات العملاء إلى أدوات التحليل
تشغيل رسائل البريد الإلكتروني أو الرسائل القصيرة أو WhatsApp من جهات خارجية عند أحداث رحلة معينة

كيفية إعداد عنصر Webhook

إضافة عنصر Webhook

اسحب وأفلت عنصر Webhook إلى لوحة الرسم. ضع Webhook في أي مكان تريده، مع الأخذ في الاعتبار معلومات الرحلة التي سترسلها إلى خدمة جهة خارجية.

لوحة رحلة العميل مع خطوة webhook Amplitude محددة بعد عناصر الدخول والانتظار

تسمية خطوة Webhook وتحديد عنوان URL ونوع الطلب

في حقل STEP NAME، أدخل اسمًا للـ webhook. قد يكون من المفيد تسمية webhooks وفقًا للخدمات التي ترسل البيانات إليها أو حالة الاستخدام.

بعد ذلك، في حقل URL، حدد عنوان URL للطلب الذي يجب إرسال البيانات إليه. بجوار حقل URL، حدد نوع الطلب من القائمة المنسدلة REQUEST TYPE: GET أو POST.

واجهة تكوين Webhook تظهر حقل URL والقائمة المنسدلة REQUEST TYPE لاختيار طريقة GET أو POST

تكوين الرؤوس (Headers)

في قسم HEADERS، قم بتعيين نوع المحتوى.

بشكل افتراضي، نوع المحتوى هو application/json. إذا كانت الخدمة التي ترسل إليها الـ webhook تتطلب نوع محتوى آخر، فأدخل النوع المناسب في قيمة رأس Content-Type.

أمثلة على أنواع المحتوى هي:

x-www-form-urlencoded
text/plain
text/xml

أضف رؤوسًا إضافية إذا لزم الأمر بالنقر فوق + ADD HEADER. يمكنك إزالة أي رأس بالنقر فوق أيقونة ‘x’ بجواره.

أضف أي رأس مصادقة تتطلبه نقطة النهاية الخاصة بك، على سبيل المثال:

Authorization: Bearer <token>
X-Api-Key: <key>
Authorization: Basic <base64(user:pass)>

يتم دعم سر ثابت في رأس فقط. لا يتم دعم تدفقات تبادل رموز OAuth2 و mTLS وتوقيع الطلبات من جانب Pushwoosh. يمكنك أيضًا تقييد نقطة النهاية إلى عناوين IP الخاصة بـ Pushwoosh بدلاً من، أو بالإضافة إلى، سر الرأس. راجع عناوين IP الخاصة بـ Pushwoosh.

لمصادقة HTTP Basic على وجه التحديد، قم بما يلي:

افتح محرر نصوص عادي واكتب اسم المستخدم وكلمة المرور بدون مسافات، مفصولة بنقطتين رأسيتين. على سبيل المثال: <username>:<password>
قم بترميز هذه السلسلة إلى Base64.
انسخ سلسلة Base64 الناتجة (على سبيل المثال، <base64-encoded-string>).
في إعدادات webhook، أضف رأس Authorization بالقيمة: Basic <base64-encoded-string>. تأكد من وجود مسافة بعد كلمة “Basic”.

مثال على رأس Authorization للمصادقة الأساسية في إعدادات webhook يظهر رؤوس Content-Type و Authorization

تمييز قيمة رأس كسرية

انقر على أيقونة العين بجوار قيمة الرأس لإخفائها. يخفي Pushwoosh هذه القيمة في كل مكان قد تترك فيه الخدمة: في واجهة المستخدم، وفي استجابات API، وفي سجل إصدارات الرحلة.

قائمة رؤوس Webhook مع قيمة Authorization مقنعة وأيقونة عين معطلة بجوار قيمة Content-Type غير مقنعة مع أيقونة عين نشطة

الإخفاء التلقائي. يتم إخفاء الرؤوس التي تبدو أسماؤها كبيانات اعتماد تلقائيًا، حتى لو لم تنقر أبدًا على أيقونة العين. وهذا يشمل Authorization، Proxy-Authorization، Cookie، Set-Cookie، وأي اسم يحتوي على token، secret، password، credential، auth، أو api-key/api_key/apikey (بواصلة، أو شرطة سفلية، أو بدون فاصل).
تغيير قيمة مخفية. انقر في الحقل الذي يظهر •••••••• واكتب القيمة الجديدة. لا يوجد زر للكشف عن القيمة المخزنة. تظل أيقونة العين مقفلة أثناء عرض القناع. لإزالة علامة السر من رأس، اكتب قيمة جديدة أولاً، ثم انقر على الأيقونة.
إعادة تسمية رأس مخفي. إعادة تسمية رأس تظهر قيمته حاليًا كقناع يمسح تلك القيمة. أدخلها مرة أخرى تحت الاسم الجديد. إعادة تسمية رأس يحمل حاليًا قيمة كتبتها للتو يحتفظ بتلك القيمة.

إضافة نص طلب JSON

في قسم DATA، أدخل نص طلب JSON الخاص بك. تأكد من أن نص الطلب بتنسيق JSON صحيح.

مثال:

{
  "hwid": "{{device:hwid}}"
}

استخدام البيانات الديناميكية ووحدات الماكرو

تتيح لك لوحة DATA BUILDER إدراج معلومات ديناميكية (مثل بيانات المستخدم أو الجهاز أو العلامة أو الحدث) مباشرة في نص طلب JSON الخاص بك. باستخدام البيانات الديناميكية، يمكنك تضمين قيم خاصة بالمستخدم الفردي الذي يتقدم عبر الرحلة.

لهذا:

حدد فئة. يمكنك سحب البيانات من ثلاث فئات:

الجهاز (Device): استخدم بيانات الجهاز عندما تحتاج إلى معلومات فنية مرتبطة بجهاز المستخدم.
العلامة (Tag): استخدم بيانات العلامة عندما تريد إرسال معلومات مخزنة في ملف تعريف المستخدم.
الحدث (Event): استخدم بيانات الحدث عندما يجب أن يرسل webhook القيم من الحدث المشغل للرحلة.

حدد معلمة (على سبيل المثال، HWID، الفئة المفضلة، إلخ).
يقوم Pushwoosh بإنشاء ماكرو يبدو كالتالي:

{{tag:Language}}

انسخ الماكرو والصقه في نص JSON الخاص بك في قسم DATA.

عندما يتم تشغيل webhook في رحلة حية، يستبدل Pushwoosh الماكرو تلقائيًا بالقيمة الفعلية لذلك المستخدم.

إدراج العناصر النائبة للبيانات الديناميكية في نص طلب webhook

كتابة عناصر نائبة إضافية يدويًا

العنصر النائب هو ماكرو تكتبه يدويًا بدلاً من إنشائه من فئة DATA BUILDER. تغطي لوحة DATA BUILDER فقط بيانات الجهاز (Device) و العلامة (Tag) و الحدث (Event). اكتب هذه العناصر النائبة مباشرة في قسم URL أو HEADERS أو DATA بدلاً من ذلك. لا تظهر في اللوحة:

العنصر النائب	القيمة
`{{application_code}}`	رمز التطبيق الخاص بالتطبيق الذي ينتمي إليه المسافر.
`{{traveler:id}}`	المعرف الذي يخصصه Pushwoosh لهذا المسافر لتشغيل هذه الرحلة.
`{{journey:uuid}}`	UUID الخاص بهذه الرحلة.
`{{journey:name}}`	اسم هذه الرحلة.
`{{point:uuid}}`	UUID الخاص بخطوة Webhook هذه.
`{{point:name}}`	STEP NAME الخاص بخطوة Webhook هذه.
`{{event:name}}`	اسم الحدث الذي أدى إلى دخول هذا المسافر إلى الرحلة.
`{{device:platform}}`	منصة الجهاز، على سبيل المثال `Android` أو `iOS`.
`{{device:push_subscribed}}`	ما إذا كان المسافر مشتركًا في إشعارات الدفع — `true` أو `false`.
`{{now}}`	التاريخ والوقت الحاليان، ISO 8601، UTC.
`{{now:unix_ms}}`	الوقت الحالي بالمللي ثانية يونكس.
`{{tags:all}}`	كل قيمة علامة لجهاز المسافر، ككائن JSON واحد. استخدمه بدون علامات اقتباس، على سبيل المثال `"user_properties": {{tags:all}}`. وضعه بين علامات اقتباس يحول الكائن إلى سلسلة مهربة بدلاً من ذلك.

الحفاظ على نوع العنصر النائب في نص JSON

يصبح العنصر النائب داخل علامات الاقتباس دائمًا سلسلة JSON، بغض النظر عن نوع القيمة الفعلي. نفس العنصر النائب بمفرده، بدون علامات اقتباس حوله، يحتفظ بنوع القيمة الخاص به بدلاً من ذلك: يبقى الرقم رقمًا، وتبقى true/false قيمة منطقية، وتصبح القائمة مصفوفة JSON. يجب أن يكون العنصر النائب غير المقتبس هو القيمة الكاملة للحقل — يعمل "age": {{tag:Age}}، لكن "note": prefix{{tag:Age}}suffix لا يعمل، لأن كل شيء خارج علامات الاقتباس يُكتب تمامًا كما هو مكتوب والأحرف الإضافية تكسر JSON.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

هنا يرسل age القيمة الرقمية للعلامة (34)، بينما يرسل age_as_text السلسلة "34". استخدم أيهما يتوقعه الحقل في الطرف المتلقي. إذا لم يكن للعلامة قيمة، فإن العنصر النائب غير المقتبس لا يزال يحل إلى سلسلة فارغة، وليس رقمًا أو false. راجع الملاحظة تحت إضافة نص طلب JSON.

تعيين بيانات استجابة webhook للمتغيرات

بالإضافة إلى إرسال البيانات، يمكن لخطوة Webhook الاحتفاظ بالقيم من الرد الذي ترسله خدمتك. أنت تعطي كل قيمة اسمًا (Attribute). يمكن للخطوات اللاحقة استخدام هذا الاسم بنفس الطريقة التي تستخدم بها قيم استجابة webhook الأخرى. على سبيل المثال، قم بتعيين علامة باستخدام تحديث ملف تعريف المستخدم، أو جدولة تأخير زمني من تاريخ أعادته الخدمة. للحصول على مثال كامل للرحلة، راجع استخدام بيانات استجابة webhook في رحلتك.

مثال: يعيد CRM معرف مستخدم. تقوم بتخزينه كـ Attribute crm_user_id. ثم يقوم تحديث ملف تعريف المستخدم بكتابته إلى علامة.

قبل أن تقوم بتعيين أي شيء، احصل على استجابة عينة واحدة من الخدمة. اسأل المطور الخاص بك، أو افتح مكالمة ناجحة في سجل المكالمات (Calls log) بعد اختبار وانظر إلى نص الاستجابة. تحتاج إلى أسماء الحقول من ذلك الرد لبناء Path.

في قسم RESPONSE MAPPING، انقر فوق + ADD MAPPING واملأ حقلين لكل قيمة تريد التقاطها:

المسار (Path): موقع القيمة داخل نص استجابة JSON، مع نقاط بين المستويات
السمة (Attribute): الاسم الذي ستستخدمه لاحقًا في الرحلة

قسم تعيين الاستجابة مع حقلي المسار والسمة وزر إضافة تعيين في إعدادات webhook

على سبيل المثال، إذا استجاب CRM الخاص بك بـ:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

قم بتعيين Path إلى data.user.id.
قم بتعيين Attribute إلى crm_user_id.

بعد أن يجتاز المستخدم هذه الخطوة، يمكن للعناصر اللاحقة اختيار Attribute crm_user_id بنفس الطريقة التي تختار بها قيم استجابة webhook الأخرى.

لا يمكن لـ تقسيم الشرط (Condition split) استخدامها مباشرة. قيم webhook المعينة ليس لها نوع. احفظ القيمة كعلامة أولاً، ثم تفرع بناءً على تلك العلامة. راجع مقارنة قيمة webhook في تقسيم الشرط.

لحقل واحد، يعمل Path والقيم على النحو التالي:

اكتب أسماء الكائنات بنقاط: data.user.id.
بالنسبة لقائمة، استخدم رقم موضع لأخذ عنصر واحد. العنصر الأول هو 0، لذا results.0.code هو حقل code للعنصر الأول. لتعيين كل عنصر في قائمة، راجع تعيين كل عنصر في مصفوفة.
لا يمكنك تعيين بعض العناصر فقط في قائمة. بالنسبة لقائمة، يكون إما موضع واحد أو كل عنصر.
يحتفظ Pushwoosh بالقيمة كما أرسلتها الخدمة (نص، رقم، أو صحيح/خطأ). يبقى الرقم 100 رقمًا. يبقى النص "100" نصًا ولن يعمل حيث تتوقع الرحلة رقمًا. لتاريخ تأخير زمني، يجب أن تعيد الخدمة تنسيقًا يقبله تأخير زمني. يمكن أن يذهب عدد عشري مثل 19.99 إلى علامة من نوع السعر (Price).
إذا لم يكن الرد JSON صالحًا، أو لم يتطابق Path مع أي حقل، فلن يتم إنشاء تلك السمة لهذا المستخدم. لا تزال خطوة Webhook تنتهي كالمعتاد. لا توجد لافتة خطأ. تحقق من نص الاستجابة في سجل المكالمات (Calls log) وأصلح Path إذا كانت القيمة مفقودة في المراحل التالية.

تعيين كل عنصر في مصفوفة

في بعض الأحيان، لا تحتوي استجابة webhook على قيمة واحدة فقط. بل تحتوي على قائمة، مثل كل منتج في طلب، أو كل عنصر في عربة تسوق، أو كل نتيجة من بحث. عادةً ما يلتقط تعيين الاستجابة قيمة واحدة لكل حقل، لذا بدون هذا ستحصل فقط على قيمة واحدة معينة من تلك القائمة، وسيتم فقدان الباقي.

ضع * في حقل Path حيث توجد القائمة. ثم يلتقط Pushwoosh قيمة من كل عنصر في القائمة، وليس فقط من موضع واحد. على سبيل المثال، إذا كانت القائمة تسمى items وكل عنصر يحتوي على item_name، فقم بتعيين Path إلى items.*.item_name.

في RESPONSE MAPPING، انقر فوق + ADD MAPPING واملأ الحقلين كالمعتاد، مع * لتحديد القائمة:

المسار (Path): موقع القيمة داخل الاستجابة، مع * حيث توجد القائمة. مثال: items.*.item_name.
السمة (Attribute): الاسم الذي ستستخدمه لاحقًا. ما تكتبه هنا يقرر كيف ستحصل على النتائج:
- قم بتضمين {n} في الاسم، على سبيل المثال item_{n}، للحصول على كل عنصر كقيمة خاصة به، مرقمة من 1: item_1، item_2، item_3، وهكذا. يمكن أن يكون {n} في أي مكان في الاسم، على سبيل المثال item_{n}_sku.
- اترك {n} خارجًا، على سبيل المثال item_names، لدمج كل عنصر في قيمة واحدة، مفصولة بفواصل: Sofa, Lamp, Rug.

$صف تعيين الاستجابة مع تعيين المسار إلى items.*.item_name والسمة إلى item_{n}}$

تبدأ مواضع قائمة المسار من 0 (items.0.item_name هو العنصر الأول). تبدأ أسماء السمات المبنية بـ {n} من 1 (item_1 هو ذلك العنصر الأول). هذان ترقيمان مختلفان.

إذا كنت تحتاج فقط إلى عنصر واحد من القائمة، فاستخدم رقمًا في Path بدلاً من *، على سبيل المثال items.0.item_name.

مثال

إذا استجاب CRM الخاص بك بـ:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

قم بتعيين Path إلى items.*.item_name و Attribute إلى item_{n} للحصول على ثلاث قيم منفصلة: item_1 هو Sofa، و item_2 هو Lamp، و item_3 هو Rug.
قم بتعيين Attribute إلى item_names بدلاً من ذلك للحصول على قيمة واحدة: item_names هو Sofa, Lamp, Rug.

يمكنك استخدام القيم المعينة لاحقًا في الرحلة مثل أي سمة استجابة webhook أخرى:

تحديث ملف تعريف المستخدم: حفظ قيمة إلى علامة
تأخير زمني: الانتظار حتى تاريخ من الاستجابة
المحتوى الديناميكي: تخصيص محتوى الرسالة

استخدام بيانات استجابة webhook في رحلتك

المهلة، وإعادة المحاولة، والطلبات الفاشلة

ينتظر Pushwoosh لمدة تصل إلى 10 ثوانٍ للحصول على استجابة. تقتصر خطوة Webhook بأكملها، بما في ذلك إرسال الطلب ومعالجة الاستجابة، على 30 ثانية.

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

عند استجابة 500 أو 502 أو 503 أو 504، أو خطأ في الشبكة مثل فشل الاتصال، يعيد Pushwoosh محاولة الطلب مرة واحدة قبل الاستسلام. لا يتم إعادة محاولة الطلب الذي تنتهي مهلته — راجع ماذا يحدث عند فشل الطلب أدناه. لا يتم إعادة محاولة أي استجابة أخرى غير 2xx أيضًا.

حدود المعدل

يحد Pushwoosh من عدد طلبات webhook التي يمكن للحساب إرسالها في الثانية. تم تحديد الحد بشكل جيد فوق ذروات حركة المرور الحقيقية، لذلك لا تتأثر الرحلات العادية. ينتظر الاندفاع الذي يتجاوزه لفترة وجيزة للحصول على مساحة قبل الفشل.

فترة تهدئة نقطة النهاية

إذا فشلت نقطة النهاية عدة مرات متتالية، يتوقف Pushwoosh عن إرسال طلبات إليها لفترة من الوقت بدلاً من إعادة محاولة نقطة نهاية معطلة على كل مسافر، بدءًا من 30 ثانية وتتضاعف عند الفشل الإضافي حتى 5 دقائق. يمسح طلب ناجح واحد هذا ويستأنف التسليم العادي.

ماذا يحدث عند فشل الطلب

لا يحتوي عنصر Webhook على فرع منفصل للطلبات الفاشلة. أي مما يلي يسقط المسافر من الرحلة في هذه الخطوة:

السبب	ما الذي يثيره
عنوان نقطة النهاية محظور	عنوان URL خاص أو داخلي أو استرجاعي أو محلي للارتباط، بما في ذلك نقاط نهاية البيانات الوصفية السحابية
حد المعدل	تم تجاوز حد طلبات webhook للحساب في الثانية ولم تفتح مساحة خلال الانتظار القصير
فترة تهدئة نقطة النهاية	فشلت نقطة النهاية عدة مرات متتالية ويقوم Pushwoosh بتخطيها مؤقتًا
المهلة	لا توجد استجابة في غضون 10 ثوانٍ، أو تتجاوز الخطوة سقفها البالغ 30 ثانية
خطأ في الشبكة	لم يتمكن الطلب من الوصول إلى نقطة النهاية على الإطلاق
استجابة غير 2xx	أعادت نقطة النهاية حالة خطأ لم تتم إعادة محاولتها، أو تمت إعادة محاولتها مرة واحدة وفشلت مرة أخرى

راجع خطأ في الطلب.

إذا كنت لا تستطيع تحمل خسارة المسافرين هنا، فاجعل نقطة النهاية الخاصة بك تعيد دائمًا استجابة 2xx وضع أي حالة فشل في نص الاستجابة بدلاً من ذلك، على سبيل المثال كقيمة يمكن لـ تعيين الاستجابة التقاطها.

ينطبق هذا على كل خطوة Webhook، بما في ذلك تلك التي تم إنشاؤها سابقًا. سيبدأ عنوان نقطة النهاية الذي يطابق الآن قاعدة العنوان المحظور أعلاه في الفشل بنفس الطريقة.

على عكس الطلب الفاشل، فإن الاستجابة التي تصل ولكن لا يتم تعيينها بشكل نظيف، مثل JSON غير صالح، أو Path غير محلول، أو نص يزيد عن 64 كيلوبايت، لا تسقط المسافر. راجع الملاحظة تحت تعيين الاستجابة أعلاه.

اختبار Webhook

انقر فوق Test webhook للتحقق من أن تكوين webhook الخاص بك صحيح وأن الطلب يتم إرساله بنجاح.

إذا كان الرأس لا يزال يظهر القناع المخزن، يقوم Pushwoosh بملء القيمة الحقيقية المحفوظة لطلب الاختبار. لا تظهر القيمة أبدًا في متصفحك.

يعمل هذا الاستبدال فقط لرأس تم حفظه بالفعل في هذه الخطوة بالضبط. الخطوة التي لم تحفظها بعد، أو التي نسختها للتو، ليس لها قيمة محفوظة خلف القناع، لذلك يرسل Pushwoosh طلب الاختبار بدون هذا الرأس.

بعد اختبار ناجح (أو مكالمة حية)، افتح Calls log، وقم بتوسيع الصف، وقارن نص الاستجابة بكل Path. يجب أن يوجد الحقل تمامًا كما في Path. إذا نجح الطلب ولكن خطوة لاحقة ليس لها قيمة، فعادةً ما لا يتطابق Path مع الاستجابة. لن تظهر خطوة Webhook خطأ لذلك.

حفظ التكوين الخاص بك

انقر فوق Save لحفظ تكوين webhook الخاص بك.

سجل المكالمات (Calls log)

افتح علامة التبويب Calls log في درج النقطة لترى ما أرسله Pushwoosh بالفعل لهذه الخطوة: الوقت، والمستخدم، والنتيجة، والمدة، بالعودة إلى 30 يومًا.

قم بالتصفية حسب النتيجة (Success، HTTP error، No response) أو ابحث عن طريق User ID أو HWID الدقيق. انقر فوق صف لتوسيعه ورؤية الطلب (الطريقة، وعنوان URL، والنص) و، اعتمادًا على النتيجة، إما الاستجابة (الحالة والنص) أو نص الخطأ. تغطي Duration الخطوة بأكملها، بما في ذلك الوقت الذي يقضيه في إعادة المحاولة التلقائية.