Webhooks والأحداث

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

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

إضافة Webhook

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

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

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

الأحداث

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

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

الحمولة

كل تسليم طلب 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.