الويب هوك

يرسل الويب هوك كل عميل محتمل ملتقَط إلى عنوان على خادمك. وتستلم Zapier وMake وn8n وPabbly Connect الجسم نفسه.

ما تحتاجه

• عنوان https يقبل طلب POST. يُرفض http العادي.
• الويب هوك مربوطًا في التطبيق. راجع Webhook.

الطلب

طلب POST واحد لكل عميل بجسم JSON وهذه الترويسات:

• user-agent: ‏Tafsee-Popup-Webhook/1.0
• x-tafsee-event: ‏popup.lead.captured
• x-tafsee-delivery: مرجع العميل. يبقى نفسه في كل إعادة محاولة للعميل نفسه، فيمكنك إسقاط المكرر.
• x-tafsee-timestamp: وقت الإرسال بثواني يونكس.
• x-tafsee-signature: ‏sha256=‎ متبوعة بقيمة hex (انظر أدناه).

الجسم

{
  "event": "popup.lead.captured",
  "leadId": "…",
  "leadRef": "…",
  "capturedAt": "2026-10-12T10:15:00.000Z",
  "workspaceId": "…",
  "site": { "id": "…", "domain": "example.com" },
  "campaign": { "id": "…", "name": "Welcome offer", "type": "lightbox" },
  "variantId": null,
  "lead": {
    "email": "shopper@example.com",
    "firstName": "…", "lastName": "…", "phone": "…", "company": "…",
    "consent": true,
    "couponCode": "WELCOME10",
    "customFields": { "size": "M" }
  },
  "fields": { "…": "…" },
  "page": { "url": "…", "title": "…", "referrer": "…" },
  "utm": { "utm_source": "instagram" },
  "device": "mobile",
  "country": "SA",
  "locale": "ar"
}

• يحمل lead البيانات الأساسية، ويحمل customFields إجابات أسئلة نموذجك الخاصة حسب معرّف الحقل.
• يحمل fields الصفوف التي اخترتها في جدول الحملة ما الذي يُرسَل بالأسماء التي سمّيتها. ودون صفوف يحمل قيم النموذج الخام.
• يُضبط variantId عندما يأتي العميل عبر نسخة من اختبار A/B.
• العميل التجريبي المرسل من التطبيق يحمل أيضًا "test": true. تجاوزه في نظامك.

كيف ترد

• ردّ بأي حالة 2xx لقبول العميل.
• ردّ خلال 8 ثوانٍ. الرد الأبطأ يُعدّ فشلًا وتُعاد محاولته.
• الحالة 408 أو 429 أو أي 5xx تُعاد محاولتها: بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 12 ساعة، أي ست محاولات إجمالًا.
• أي حالة 4xx أخرى تُعدّ رفضًا. يُعلَّم العميل بالفشل لهذا الويب هوك فورًا ولا تُعاد محاولته تلقائيًا.

العميل محفوظ في تفسير في كل الأحوال، ويمكن إعادة إرسال التسليم الفاشل يدويًا. راجع تسليم العملاء المحتملين وإعادة الإرسال.

التوقيع

ترويسة x-tafsee-signature هي HMAC-SHA256 للطابع الزمني ثم نقطة ثم الجسم الخام، محسوبة بسرّ توقيع يخص الربط، ومكتوبة بصيغة hex بعد sha256=‎.

لا يعرض التطبيق سرّ التوقيع حاليًا، فلا يمكنك التحقق من التوقيع بعد. إلى أن يعرضه احمِ عنوانك بطريقة أخرى: استخدم عنوانًا طويلًا يصعب تخمينه واحتفظ به لنفسك.

نصائح

• استخدم x-tafsee-delivery مفتاحًا لمنع التكرار.
• أنجز العمل البطيء بعد الرد لا قبله.
• استخدم إرسال عميل تجريبي في بطاقة الويب هوك لإرسال عيّنة إلى عنوانك.

إن لم ينجح الأمر

• لا يصل شيء: لا حملة محددة للويب هوك. راجع ربط أداة: كيف يعمل.
• العملاء يحملون فشل: افتح أحدهم لقراءة ردّ خادمك ورمز حالته.
• تستلم العميل نفسه مرتين: ردّ خادمك ببطء أو بخطأ في المرة الأولى. أسقط المكرر عبر x-tafsee-delivery.

مواضيع ذات صلة

• Webhook
• تسليم العملاء المحتملين وإعادة الإرسال
• أحداث الصفحة وعناصر HTML