ويب هوكس الواردة

📥 الويب هوكس الواردة

استقبل الأحداث من المنصات الخارجية ومنح البذور لعملائك تلقائيًا. تتيح لك الويب هوكس الواردة ربط أي أداة خارجية — تطبيقات الاختبارات، النماذج، منصات المراجعة، Zapier، Make، والمزيد — ببرنامج ولاء LoyaltyTree الخاص بك.

كيف يعمل

يستخدم نظام الويب هوكس الواردة نموذج المصادر والرموز:

1. إنشاء مصدر — يمثل المصدر منصة أو أداة خارجية (مثل "Typeform"، "Zapier"، "تطبيق الاختبار الخاص بي"). يحصل كل مصدر على عنوان URL فريد للويب هوك ومفتاح سري للأمان.
2. إضافة رموز إلى المصدر — يحدد كل رمز إجراءً معينًا يمنح البذور (مثل "quiz_completed"، "form_submitted"، "birthday_claimed"). يمكنك تحديد عدد البذور التي يمنحها كل رمز، مع حدود اختيارية.
3. إرسال طلبات POST — ترسل منصتك الخارجية طلب POST إلى عنوان URL للويب هوك مع الرمز ومعلومات العميل. يجد LoyaltyTree العميل أو ينشئه ويمنح البذور تلقائيًا.

البدء

الخطوة 1: إنشاء مصدر ويب هوك

انتقل إلى المتاجر → [متجرك] → التكاملات → الويب هوكس الواردة. انقر على + إضافة مصدر وأعطه اسمًا يصف المنصة الخارجية (مثل "اختبارات Typeform" أو "أتمتة Zapier").

عند إنشاء المصدر، ستتلقى:

• عنوان URL للويب هوك — النقطة التي سترسل إليها منصتك الخارجية الطلبات
• سر الويب هوك — مفتاح سري لتوقيع الطلبات (موصى به للأمان)

الخطوة 2: إضافة الرموز

يمثل كل رمز إجراءً معينًا تريد مكافأته. انقر على + إضافة رمز على المصدر الخاص بك لإنشاء واحد.

الحقل	مطلوب	الوصف
الرمز	نعم	القيمة الدقيقة المرسلة في حمولة الويب هوك (مثل quiz_completed). يجب أن تتطابق مع ما ترسله منصتك الخارجية.
اسم العرض	نعم	اسم سهل الفهم يظهر في لوحة الإدارة وسجل المعاملات (مثل "الاختبار مكتمل").
الوصف	لا	ملاحظة اختيارية لفريقك حول متى يتم استخدام هذا الرمز.
كمية البذور	نعم	عدد البذور التي سيتم منحها في كل مرة يتم فيها تفعيل هذا الرمز. الافتراضي هو 1.
الحد الأقصى للبذور/العميل	لا	الحد الأقصى من البذور التي يمكن أن يكسبها عميل واحد من هذا الرمز. اتركه فارغًا لعدم وجود حد. بمجرد أن يصل العميل إلى هذا الحد، ستعود مكالمات الويب هوك الإضافية لهم بنجاح ولكن ستمنح 0 بذور.
فترة الانتظار (ساعات)	لا	الحد الأدنى من الساعات بين الجوائز لنفس العميل على هذا الرمز. يمنع الإساءة عن طريق تحديد عدد المرات التي يمكن أن يكسب فيها العميل البذور. اتركه فارغًا لعدم وجود فترة انتظار.
مفعل	—	تبديل لتفعيل أو تعطيل هذا الرمز دون حذفه. الرموز المعطلة تعيد خطأ 403.

شرح الرموز والحدود

تعمل الرموز وحدودها معًا لتمنحك تحكمًا دقيقًا في كيفية منح البذور:

كمية البذور

يمتلك كل رمز كمية ثابتة من البذور. في كل مرة يتم فيها تفعيل الويب هوك بهذا الرمز، يتلقى العميل بالضبط هذا العدد من البذور. على سبيل المثال، إذا قمت بتعيين "quiz_completed" إلى 5 بذور، فإن كل مكالمة ويب هوك مؤهلة تمنح 5 بذور.

الحد الأقصى للبذور لكل عميل

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

فترة الانتظار (ساعات)

تحدد الحد الأدنى من الوقت الذي يجب الانتظار بين منح البذور لنفس العميل على نفس الرمز. يبدأ مؤقت فترة الانتظار من آخر جائزة ناجحة.

تنسيق الطلب

أرسل طلب POST إلى عنوان URL للويب هوك الخاص بك مع جسم JSON التالي:

{
  "code": "your_code_here",
  "customer": {
    "email": "customer@example.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* يجب أن يكون واحد على الأقل من البريد الإلكتروني أو معرف_shopify_customer مطلوبًا. البريد الإلكتروني مطلوب عندما لا يكون العميل موجودًا بالفعل في LoyaltyTree.

التحقق من توقيع HMAC (موصى به)

للتحقق من أن الطلبات تأتي حقًا من منصتك (وليس من شخص ما وجد عنوان URL للويب هوك الخاص بك)، قم بتوقيع طلباتك باستخدام HMAC-SHA256.

رؤوس التوقيع المدعومة (يتحقق LoyaltyTree من كل هذه):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

يمكن أن تكون قيمة التوقيع إما التجزئة المشفرة بالهيكس الخام أو مسبوقة بـ sha256= (يتم قبول كلا التنسيقين).

بديل: مصادقة الرمز العادي

إذا لم يكن توقيع HMAC ممكنًا في منصتك، يمكنك تمرير سر الويب هوك الخاص بك كرمز عادي في رأس X-Token. سيقارن LoyaltyTree مباشرة مع سرك.

مثال: التوقيع باستخدام Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completed',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'your_webhook_secret')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

مثال: التوقيع باستخدام Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completed",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'your_webhook_secret',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

مثال: استخدام cURL (للاختبار)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: your_webhook_secret" \
  -d '{"code":"quiz_completed","customer":{"email":"jane@example.com"}}'

تنسيق الاستجابة

استجابة ناجحة (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

ناجحة ولكن محدودة (200)

عندما تمنع فترة الانتظار أو الحد الأقصى للبذور الجائزة، لا تزال تحصل على استجابة 200 ولكن مع 0 بذور وتفسير:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "فترة الانتظار نشطة. حاول مرة أخرى بعد 18 ساعة."
}

// أو
{
  "success": true,
  "seeds_awarded": 0,
  "message": "تم منح الحد الأقصى من البذور (15) بالفعل لهذا الرمز."
}

استجابات الأخطاء

أمثلة حالات الاستخدام

الاتصال بـ Zapier

Zapier هو واحد من أكثر الطرق شيوعًا لربط LoyaltyTree بمئات التطبيقات الأخرى. نحن نبني تكامل LoyaltyTree مخصص في متجر تطبيقات Zapier، مما سيجعل الإعداد أسهل بكثير — ابحث عنه في سوق Zapier.

في هذه الأثناء، يمكنك استخدام إجراء Webhooks by Zapier للاتصال الآن:

الاتصال بـ Make (Integromat)

يمكنك أيضًا استخدام وحدة HTTP / إجراء طلب من Make لإرسال الويب هوكس إلى LoyaltyTree. قم بتكوينها بنفس طريقة Zapier — قم بتعيين عنوان URL، أضف جسم JSON مع code و customer، وأدخل سرك في رأس X-Token.

سجلات الويب هوك

يتم تسجيل كل مكالمة ويب هوك واردة ومرئية في قسم الويب هوكس الواردة في صفحة التكاملات الخاصة بك. تظهر السجلات:

• الطابع الزمني – متى تم استلام الويب هوك
• المصدر – أي مصدر استقبله
• الحالة – نجاح أو فشل
• التفاصيل – الرمز المستخدم، البذور الممنوحة، أو رسالة الخطأ
• الحمولة – جسم الطلب الكامل (مشفر أثناء الراحة)

استخدم السجلات للتحقق من أن تكامل الخاص بك يعمل بشكل صحيح ولتشخيص أي مشاكل.

استكشاف الأخطاء وإصلاحها

الأمان

• يحصل كل مصدر على سر ويب هوك فريد مكون من 64 حرفًا، يتم إنشاؤه تلقائيًا ومشفّر أثناء الراحة
• يمكن إعادة توليد الأسرار في أي وقت من إعدادات المصدر (يتوقف السر القديم عن العمل على الفور)
• تكون حمولة الطلبات مشفرّة في السجلات من أجل الخصوصية
• يستخدم التحقق من التوقيع مقارنة آمنة من حيث التوقيت لمنع هجمات التوقيت
• يمكن تعطيل المصادر والرموز بشكل فردي دون حذفها