قائمة التوثيق

Webhooks والأحداث

ترسل Webhooks الحساب ما يحدث في حسابك كله إلى عنوان URL تختاره، لحظة حدوثه: عميل محتمل جديد، أو اجتماع محجوز، أو صفقة تنتقل بين المراحل. وهي ما تستخدمه تكاملات Zapier وn8n في الخلفية، ويمكنك توجيهها إلى نقطة النهاية الخاصة بك أيضًا. إذا كنت تستخدم Zapier وحده، فلا حاجة إلى إضافة Webhook بنفسك: تبدأ بطاقة Zapier في صفحة المطوّرون ‏Zap من قالب، ويُعدّ الـ Zap الـ Webhook الخاص به بنفسه.

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

إضافة Webhook

  1. انتقل إلى المطوّرون في لوحة التحكم وابحث عن بطاقة خطافات الويب.
  2. أدخل عنوان URL لنقطة النهاية (عنوان https:// عام) وحدد الأحداث التي تريدها.
  3. انقر إضافة خطاف ويب وانسخ سر التوقيع. لا يُعرض إلا هذه المرة.

يعرض كل Webhook طريقة إنشائه (لوحة التحكم أو API أو Zapier أو n8n)، وحالته، وآخر تسليم له. يرسل إرسال تجربة نموذجًا للحدث المختار، مع "test": true داخل data. ويزيل حذف الـ Webhook. يمكن أن يكون لكل حساب حتى 50 منها.

لا يستطيع إضافة Webhooks أو حذفها إلا مالك الحساب، وقد يُطلب منه تسجيل الدخول مجددًا أولًا.

الأحداث

الحدثمتى يُطلق
interaction.receivedعندما يتفاعل مستلم مع رسالة: تصويت أو تقييم أو إجابة اختبار أو نقرة متتبَّعة أو شراء وغير ذلك. التكرارات المحذوفة بإزالة التكرار لا تُطلقه.
form.submittedعند إرسال نموذج داخل رسالة (source: "email-form") أو نموذج تسجيل (source: "signup-form").
contact.createdعند إضافة جهة اتصال إلى قائمة.
contact.updatedعند تغيّر حقول جهة اتصال. حفظ بيانات مطابقة لا يُطلقه.
lead.hotعندما تتجاوز درجة تفاعل جهة اتصال حد درجة العميل المهتم صعودًا.
lead.newعند وصول عميل محتمل جديد من نموذج تسجيل أو نموذج داخل رسالة.
booking.createdعند حجز اجتماع.
booking.cancelledعند إلغاء حجز، مع cancelledBy. إعادة الجدولة لا تُطلق أيًّا من حدثي الحجز.
deal.createdعند إنشاء صفقة، من أي مكان: اللوحة أو قاعدة تلقائية أو رحلة أو عرض أو API.
deal.stage_changedعند انتقال صفقة بين المراحل، بما في ذلك الفوز والخسارة.
purchase.completedعندما يدفع مستلم عبر الدفع داخل البريد.
journey.completedعندما تصل جهة اتصال إلى نهاية رحلة. الخروج المبكر لا يُحتسب.
experiment.decidedعندما يسجّل أحدهم قرار تجربة: فائز، أو لا فرق، أو نتيجة غير حاسمة.
experiment.completedعندما تصل النتائج النهائية لتجربة: أي حين يكتمل التحليل الذي يغطي نافذة المراقبة كاملة.
response.completedعندما يجيب مستلم عن كل عنصر تحتسبه رسالة البريد، مثل كل سؤال في استطلاع. مرة واحدة لكل مستلم ولكل رسالة.
review.submittedأرسل مستلم تقييمًا من عنصر طلب تقييم. يُطلَق مرة واحدة لكل تقييم.

تُطلق أحداث جهات الاتصال مع الاستيراد ونماذج التسجيل وواجهة API والمزامنة وموصّلات الذكاء الاصطناعي. أما عملية الكتابة الواحدة لأكثر من 500 جهة اتصال (مثل استيراد CSV كبير) فلا تُطلق أيًّا منها، حتى لا يشغّل الاستيراد آلاف التدفقات. جهة الاتصال التي تُضاف في جدول جهات الاتصال، كتابةً أو دمجًا من ملف CSV، تُطلق contact.created. أما تعديل جهات اتصال موجودة في الجدول فلا يُطلق contact.updated، ولا تُطلقه كذلك خطوات الرحلة تحديث حقل ولا الإجابات المحفوظة.

يُطلق lead.hot وlead.new بغض النظر عن مفاتيح تنبيهات العملاء المحتملين وحدودها: الاشتراك نفسه هو الموافقة.

يحمل حدثا التجارب كلاهما {experiment}، بالشكل نفسه الذي تجيب به واجهة API للتجارب: مجموعاتها، وأحدث result من التحليل، وdecision المسجَّل مع evidence الذي أعطاه التحليل له، وresultsUrl. ويُطلق experiment.completed مرة واحدة لكل تجربة، حتى حين يُسجَّل القرار مبكرًا في اختبار تتابعي. وفي التجربة داخل رحلة، يحدّد الفائز مسارًا: decision.pathIndex.

يحمل response.completed الرسالة (projectId وprojectName)، ومفتاح recipient وcontact الخاص به، وsendId وvariant حين تُرسل ضمن عملية إرسال (وإلا فالقيمة null)، والعناصر المحتسبة blockIds، وفي answers إجابة كل عنصر، وهي القيمة نفسها التي يحملها interaction.received في event.value، مع firstAnsweredAt وcompletedAt. تحتسب الرسالة كل استطلاع وتقييم واختبار وRSVP ونموذج يراه المستلم، ما لم تختر لوحة «الردود» في الاستوديو عددًا أقل، ولا يُطلق الحدث أبدًا إذا قلّ العدد عن عنصرين. تغيير إجابة لاحقًا لا يُطلقه مرة أخرى، والعرض الذي لا مستلم له (معاينة أو رابط عام) لا يكتمل أبدًا.

يحمل review.submitted الرسالة (projectId وprojectName) وblockId وما جرى تقييمه في subject (kind وid وtitle) وrating وtitle وbody وdisplayName الذي اختاره العميل وverifiedPurchase وcontact وrecipient وsubmittedAt.

الحمولة

كل تسليم طلب POST بصيغة JSON بالغلاف نفسه:

{
  "id": "evt_8c1f…",
  "type": "deal.stage_changed",
  "createdAt": 1790000000000,
  "data": {
    "deal": {
      "id": "deal_abc123",
      "title": "Annual plan",
      "value": 1200,
      "currency": "USD",
      "pipelineId": "owner_default",
      "stageId": "proposal-sent",
      "stage": "Proposal sent",
      "status": "open",
      "source": "manual",
      "listId": "list_abc123",
      "rowId": "3f6c1b0e2d…",
      "email": "[email protected]"
    },
    "fromStageId": "meeting-booked"
  }
}

قيمة id واحدة في كل تسليمات الحدث نفسه، وتُرسل أيضًا في الترويسة X-MailInApp-Idempotency-Key، فيمكنك بأمان تجاهل إعادة تسليم سبق أن عالجتها. وcreatedAt بالمللي ثانية منذ epoch.

لرؤية data لكل نوع من الأحداث، استدعِ GET /api/v1/events/sample أو استخدم إرسال تجربة.

التحقق من التوقيع

تحمل التسليمات الترويستين X-MailInApp-Timestamp وX-MailInApp-Signature، المحسوبتين تمامًا كما في Webhook المشروع. تحقّق منهما على النص الخام باستخدام سر التوقيع، وارفض الطوابع الزمنية الأقدم من بضع دقائق. تحتوي وثائق Webhook المشروع على دالة Node.js جاهزة.

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

لدى نقطة النهاية 5 ثوانٍ للرد بـ 2xx. وأي شيء آخر (انتهاء المهلة، أو حالة خطأ، أو إعادة توجيه) يُعدّ فشلًا، وتُعاد محاولة التسليم تلقائيًا بفواصل متزايدة على مدى عدة ساعات، بالنص نفسه ومفتاح منع التكرار نفسه، إلى عنوان URL الحالي للـ Webhook. ردّ بسرعة وأنجز العمل البطيء بعد ذلك.

  • إذا ردّت نقطة النهاية بـ 410 Gone، يُعطَّل الـ Webhook. هكذا يلغي عملاء REST Hooks اشتراكهم.
  • إلغاء مفتاح API يعطّل الـ Webhooks التي أُنشئت به.
  • حذف Webhook يوقف محاولاته المعلّقة.

الاشتراك عبر API

يمكن لـ Zapier وn8n وشيفرتك الخاصة إدارة الـ Webhooks باستخدام مفتاح API (Authorization: Bearer mia_live_…):

curl https://mailinapp.com/api/v1/webhooks \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'

تحتوي استجابة 201 على id الاشتراك وsecret الذي يوقّع كل تسليم. احتفظ به: لن يُعاد مرة أخرى. يعرض GET /api/v1/webhooks اشتراكاتك، ويحذف DELETE /api/v1/webhooks/{id} أحدها. يكفي اسم حدث واحد غير معروف لرفض الطلب كله. تسمح هذه المسارات بـ 30 طلبًا في الدقيقة لكل مفتاح.

العقد الكامل موجود في مواصفات OpenAPI.

قراءة نتائج التجارب

باستخدام مفتاح API، يمكن لشيفرتك قراءة تجاربك، مثلًا لجلب الأرقام فور وصول experiment.completed:

  • يسرد GET /api/v1/experiments التجارب، الأحدث أولًا. ويمكن التصفية بـ status أو kind (send أو journey) أو projectId أو journeyId.
  • يعيد GET /api/v1/experiments/{id} تجربة واحدة.
  • يعيد GET /api/v1/experiments/{id}/results التجربة مع تقريرها الكامل: الأرقام نفسها التي يحتويها تصدير JSON في صفحة النتائج، كبيانات مجمّعة فقط.

هذه المسارات للقراءة فقط. أما القفل والإطلاق والحسم ونشر الفائز فتبقى في لوحة التحكم. وتسمح بـ 60 طلبًا في الدقيقة لكل مفتاح. وتشرح صفحة قراءة نتائج التجربة ما تعنيه الأرقام.