تهيئة Webhooks

Published: ١٦ يوليو ٢٠٢٦ · Last updated: ٢٨ أغسطس ٢٠٢٦ · By Marcus Biel

تتيح Webhooks لـ Maildroppa إخطار تطبيق آخر عند حدوث أمر مهم في حسابك.

بدلاً من سؤال Maildroppa بشكل متكرر عمّا إذا كان قد تم إنشاء مشترك أو تحديثه أو إلغاء اشتراكه أو إسناد علامة إليه، يمكن لتطبيقك استلام طلب HTTPS بعد وقت قصير من وقوع الحدث.

تُعد صفحة Webhooks المكان المركزي لهذا التكامل على مستوى الحساب. يمكنك إنشاء عدة نقاط نهاية، واختيار الأحداث التي تستلمها كل نقطة نهاية، وإضافة رؤوس مصادقة، واختبار الاتصال، وفحص محاولات التسليم، وإعادة تشغيل حدث إنتاج عند الحاجة.

كيفية عمل Webhooks على مستوى الحساب

تتبع Webhook الخاصة بالحساب العملية التالية:

1. يحدث حدث في Maildroppa، مثل إنشاء مشترك.
2. يبحث Maildroppa عن كل نقطة نهاية نشطة مشتركة في ذلك الحدث.
3. ينشئ Maildroppa عملية تسليم واحدة لكل نقطة نهاية مطابقة.
4. يتم توقيع حمولة JSON باستخدام Signing secret الخاصة بـ Webhook لحسابك.
5. يرسل Maildroppa طلب HTTPS من نوع POST إلى عنوان URL المحفوظ لنقطة النهاية.
6. تتحقق نقطة النهاية لديك من التوقيع، ثم تخزّن الحدث أو تعالجه، وتعيد استجابة HTTP.
7. يسجل Maildroppa النتيجة في Delivery history ويعيد محاولة حالات الفشل المؤقتة تلقائيًا.

إذا اشتركت عدة نقاط نهاية في الحدث نفسه، فستستلم كل نقطة نهاية عملية تسليم خاصة بها. ويكون للحدث التجاري نفسه Event ID لدى جميع النقاط، بينما يكون لكل عملية تسليم Delivery ID خاص بها.

تختلف Webhooks على مستوى الحساب عن خطوة “Send a webhook” داخل Automation. تستمع Webhooks على مستوى الحساب إلى أحداث الحساب المحددة عبر Maildroppa. أما Webhook الخاصة بـ Automation فلا تُرسل إلا عندما يصل مشترك إلى تلك الخطوة تحديدًا. تستخدم كلتاهما Signing secret الخاصة بـ Webhook للحساب، ولذلك يؤثر تدوير السر في كل مستلم Webhook صادر يتحقق من توقيعات Maildroppa.

فتح صفحة Webhooks

افتح “Settings”، ثم وسّع “Developers”، واختر “Webhooks”.

تحتوي الصفحة على ثلاث مناطق رئيسية:

• Signing secret
• Endpoints
• Delivery history لنقطة النهاية المحددة

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

قبل إنشاء نقطة نهاية

جهّز مستلِمًا على خادمك قبل تهيئة Maildroppa. يجب أن يكون المستلم:

• متاحًا عبر عنوان URL عام يستخدم HTTPS.
• قادرًا على قبول طلبات POST مع جسم من نوع application/json.
• محتفظًا بجسم الطلب الخام إلى أن يتم التحقق من توقيع Maildroppa.
• معيدًا حالة 2xx فقط بعد قبول الحدث بأمان.
• معالجًا عمليات التسليم المتكررة بطريقة idempotent باستخدام Event ID.
• مستجيبًا بسرعة بدلاً من تنفيذ مهام بطيئة أثناء الطلب.

من الأنماط الموثوقة التحقق من الطلب، وتخزين Event ID والحمولة في قائمة انتظار أو قاعدة بيانات دائمة، وإعادة 200 أو 204، ثم معالجة الإجراء التجاري لاحقًا.

لا تكشف جهاز تطوير أو عنوان شبكة محلية أو نصًا برمجيًا غير محمي باعتباره مستلم Webhook للإنتاج. يقبل Maildroppa أهداف HTTPS العامة فقط، ويتحقق من الوجهة مرة أخرى عند إرسال عملية التسليم.

الخطوة 1: إنشاء Signing secret

يتم توقيع كل طلب Webhook من Maildroppa. ويستخدم المستلم لديك Signing secret للتحقق من أن الطلب أُنشئ بواسطة Maildroppa وأن الجسم لم يتغير أثناء النقل.

في أعلى الصفحة، تعرض لوحة Signing secret إحدى الحالات التالية:

• Missing — لا يوجد Signing secret حتى الآن.
• Ready — تم إعداد Signing secret.
• Loading — يسترجع Maildroppa الحالة الحالية.

انقر على “Generate secret” عندما تكون الحالة Missing.

يعرض Maildroppa السر الجديد فورًا. ويبدأ بـ whsec_. انقر على “Copy” وخزّنه في مدير الأسرار أو إعدادات البيئة المحمية التي يستخدمها المستلم لديك.

تُعرض القيمة الكاملة فقط مباشرة بعد الإنشاء أو التدوير. عند إعادة تحميل الصفحة أو مغادرتها، يعرض Maildroppa فقط وجود سر ووقت آخر تحديث له. ولا يكشف السر المخزن مرة أخرى.

إذا فقدت السر

إذا لم يعد المستلم يملك السر الحالي، فانقر على “Rotate secret” واحفظ القيمة المعروضة حديثًا.

يستبدل التدوير السر السابق فورًا. ولا يحتفظ Maildroppa بالقيمتين خلال فترة انتقالية. حدّث كل مستلم يستخدم سر الحساب هذا قبل إرسال اختبارات إضافية أو الاعتماد على عمليات تسليم الإنتاج.

تُوقّع عمليات التسليم الجديدة، وإعادات المحاولة المجدولة، والاختبارات، وعمليات إعادة التشغيل باستخدام السر الحالي وقت إجراء طلب HTTP. وهذا يعني أن عملية تسليم أُنشئت قبل التدوير قد تُوقّع بالسر الجديد عند محاولة إرسالها بعد ذلك.

تعامل مع السر كما تتعامل مع كلمة مرور

لا تضع Signing secret في تعليمات برمجية للمتصفح، أو مستودع عام، أو عنوان URL، أو صفحة خطأ، أو سجل تطبيق عادي.

لا يحتاج إلى السر سوى المستلم الموجود على الخادم. وإذا كنت تعتقد أنه انكشف، فقم بتدويره وحدّث جميع المستلمين فورًا.

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

يحتوي كل طلب على رؤوس Maildroppa التالية:

• X-Maildroppa-Event-Id — يعرّف الحدث التجاري.
• X-Maildroppa-Delivery-Id — يعرّف عملية التسليم هذه تحديدًا.
• X-Maildroppa-Timestamp — وقت التوقيع بوحدة ثواني Unix.
• X-Maildroppa-Signature — توقيع HMAC ذي إصدار.

يرسل Maildroppa أيضًا:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

يتخذ التوقيع التنسيق التالي:

v1=<lowercase hexadecimal HMAC>

ينشئه Maildroppa باستخدام HMAC-SHA256. والمحتوى الموقّع هو الطابع الزمني، يليه نقطة، ثم جسم طلب JSON الخام المطابق تمامًا:

<timestamp>.<raw request body>

استخدم Signing secret كمفتاح HMAC.

يوضح المثال التالي بلغة Node.js خطوة التحقق الأساسية. يجب أن يكون rawBody وحدات البايت الأصلية للطلب، وليس JSON جرى تحليله ثم إعادة تسلسله.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

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

لا تحلل JSON ولا تعالجه إلا بعد اجتياز كلا الاختبارين.

الأسباب الشائعة لأخطاء التوقيع

يفشل التوقيع عادةً لأحد الأسباب التالية:

• يستخدم المستلم سرًا قديمًا بعد التدوير.
• قامت برمجية وسيطة بتحليل JSON أو تغييره قبل احتساب التوقيع.
• يوقّع المستلم الجسم فقط ويحذف <timestamp>..
• يُعامَل الطابع الزمني كتاريخ منسق بدلاً من استخدام قيمة الرأس كما هي.
• تم حذف السابقة v1= من المقارنة.
• تم ترميز HMAC المحسوب بطريقة مختلفة بدلاً من استخدام النظام السداسي العشري الصغير.

سجّل Event ID وDelivery ID عند فشل التحقق، لكن لا تسجل Signing secret أو قيم الرؤوس المخصصة الحساسة أبدًا.

الخطوة 2: إضافة نقطة نهاية

انقر على “Add endpoint” في قسم Endpoints.

يحتوي المحرر على أربعة أجزاء:

• Endpoint URL
• Events
• Custom headers
• الحالة النشطة

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

تهيئة Endpoint URL

أدخل عنوان URL العام الكامل الذي يجب أن يستقبل طلبات Maildroppa، مثل:

https://integrations.example.com/webhooks/maildroppa

يجب أن يستوفي عنوان URL المتطلبات التالية:

• يجب أن يستخدم https://.
• يجب أن يحتوي على اسم مضيف عام صالح.
• يمكن أن يصل طوله إلى 2,048 حرفًا.
• لا يمكن أن يحتوي على متغيرات قالب تتضمن { أو }.
• لا يمكن أن يحتوي على اسم مستخدم أو كلمة مرور قبل اسم المضيف.
• لا يمكن أن يحتوي على جزء من عنوان URL يبدأ بـ #.
• يجب أن يستخدم منفذ HTTPS القياسي 443.
• لا يمكن أن يستخدم localhost أو عنوان IP خامًا أو اسم مضيف يُحل إلى شبكة خاصة أو محجوزة ومحظورة.

تُدعم معلمات الاستعلام، لكن لا تضع مفاتيح API أو الأسرار الأخرى في عنوان URL. تظهر عناوين URL في قائمة نقاط النهاية وبيانات التسليم. استخدم Custom header لبيانات الاعتماد بدلاً من ذلك.

لا يتبع Maildroppa عمليات إعادة التوجيه. احفظ وجهة HTTPS النهائية بدلاً من عنوان URL الذي يعيد 301 أو 302 أو 307 أو 308.

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

اختيار الأحداث

حدد حدثًا واحدًا على الأقل. لا تستلم نقطة النهاية إلا أنواع الأحداث المحددة في محررها.

تقدم الصفحة خيارات الأحداث التالية:

Subscriber Created — subscriber.created

يُرسل عند إنشاء مشترك في حساب Maildroppa.

استخدم هذا الحدث لإنشاء جهة الاتصال المقابلة في CRM أو منصة بيانات العملاء أو قاعدة بيانات داخلية أو نظام آخر يراعي الأذونات.

لا تفسر هذا الحدث على أنه دليل على إكمال كل عملية تسجيل لـ Double Opt-in. تصف حالة المشترك في الحمولة حالته الحالية.

Subscriber Updated — subscriber.updated

يُرسل عند تغير معلومات المشترك المضمنة أو قيم الحقول المخصصة.

استخدم كائن المشترك الكامل في الحمولة باعتباره تمثيل Maildroppa الحالي. تجنب افتراض أن خاصية معينة واحدة فقط هي التي تغيرت.

لإسناد العلامات وإزالتها أنواع أحداث خاصة بها، بحيث يمكن التعامل معها بشكل منفصل.

Subscriber Unsubscribed — subscriber.unsubscribed

يُرسل عندما ينتقل المشترك إلى حالة إلغاء الاشتراك من خلال إجراء إلغاء الاشتراك.

استخدم هذا الحدث لكتم جهة الاتصال في الأنظمة المتصلة. لا تعِد الاشتراك بالشخص تلقائيًا لأن نظامًا آخر لا يزال يضع جهة الاتصال في حالة نشطة.

Tag Added — subscriber.tag_added

يُرسل عند إسناد علامة إلى مشترك.

تحتوي الحمولة على المشترك والعلامة المشاركين في هذا التغيير تحديدًا.

Tag Removed — subscriber.tag_removed

يُرسل عند إزالة علامة من مشترك.

تحتوي الحمولة على المشترك المحدّث والعلامة التي أزيلت. وتُوفَّر العلامة المُزالة بشكل منفصل رغم أنها لم تعد موجودة في مصفوفة tags الحالية للمشترك.

Form Submitted — form.submitted

يُرسل عندما يرسل زائر نموذج تسجيل في Maildroppa.

تعامل معه كإشارة إلى إرسال النموذج، وليس كتأكيد على إكمال Double Opt-in. يجب أن يستمر أي سير عمل يتطلب اشتراكًا مؤكدًا في احترام حالة المشترك الحالية وعملية التأكيد.

استخدم نقاط نهاية منفصلة عندما تختلف المسؤوليات

يمكنك إرسال أحداث مختلفة إلى أنظمة مختلفة. على سبيل المثال:

• أرسل أحداث المشترك والعلامات إلى CRM.
• أرسل أحداث إلغاء الاشتراك إلى خدمة كتم.
• أرسل أحداث إرسال النماذج إلى خط تحليلات.

تقلل نقاط النهاية المنفصلة من حركة المرور غير الضرورية وتجعل تشخيص حالات الفشل أسهل. ولكل نقطة نهاية اختيار أحداث وعنوان URL ورؤوس مخصصة وحالة نشطة واختبارات وDelivery history خاصة بها.

إضافة Custom headers

الرؤوس المخصصة اختيارية. استخدمها عندما يتطلب المستلم مفتاح API أو رمز Bearer أو معرّف مستأجر أو رأسًا ثابتًا آخر.

انقر على “Add header”، ثم أدخل Header name وHeader value. تتضمن الأمثلة المناسبة:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

يمكنك إضافة ما يصل إلى 20 رأسًا مخصصًا.

أسماء الرؤوس:

• مطلوبة.
• يمكن أن يصل طولها إلى 128 حرفًا.
• يجب أن تستخدم أحرفًا صالحة لاسم رأس HTTP.
• يجب أن تكون فريدة دون اعتبار لاختلاف الكتابة بالأحرف الكبيرة والصغيرة.

قيم الرؤوس:

• مطلوبة.
• يمكن أن يصل طولها إلى 2,000 حرف.
• لا يمكن أن تحتوي على فواصل أسطر.

الأسماء التالية محجوزة ولا يمكن استبدالها برأس مخصص:

• Content-Type
• Content-Length
• Host
• User-Agent
• أي اسم يبدأ بـ X-Maildroppa-

يمنع ذلك القيمة المخصصة من استبدال رؤوس التسليم والتوقيع الخاصة بـ Maildroppa.

كيفية تخزين أسرار الرؤوس

يشفر Maildroppa قيم الرؤوس المخصصة قبل تخزينها. ولا تُعاد القيم المحفوظة إلى المتصفح بصيغة قابلة للقراءة.

عند تعديل نقطة النهاية لاحقًا، يعرض حقل القيمة عبارة “Stored value kept”. اتركه فارغًا عندما يجب أن يبقى السر الحالي دون تغيير. أدخل قيمة جديدة لاستبداله.

إذا غيّرت اسم الرأس، فأدخل القيمة مرة أخرى. يحتفظ Maildroppa بالسر المخزن فقط ما دام اسم الرأس الأصلي لم يتغير.

تؤدي إزالة صف رأس إلى إزالة ذلك الرأس من عمليات التسليم المستقبلية بعد حفظ نقطة النهاية.

تُعامل قيم الرؤوس المخصصة على أنها حساسة في معلومات الطلب المخزنة. ويتم إخفاؤها بدلاً من عرضها في Delivery history.

تعيين نقطة النهاية إلى نشطة أو غير نشطة

اترك “Active” محددًا عندما تكون نقطة النهاية جاهزة لاستقبال الأحداث فورًا.

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

نقطة النهاية غير النشطة:

• لا تستلم الأحداث الجديدة التي تقع.
• لا يمكنها إرسال Test webhook.
• تظل ظاهرة وقابلة للتحرير.
• تحتفظ بسجل Delivery history الحالي المتاح.

لا يؤدي تفعيل نقطة النهاية إلى استكمال الأحداث التي وقعت أثناء عدم نشاطها.

انقر على “Save” عندما يكون عنوان URL واختيار الأحداث والرؤوس والحالة صحيحة.

فهم قائمة نقاط النهاية

يعرض كل صف لنقطة نهاية:

• عنوان URL للوجهة.
• شارة Active أو Inactive.
• أنواع الأحداث المشترك فيها.
• عدد الرؤوس المخصصة.
• وقت آخر تحديث لنقطة النهاية.

الإجراءات المتاحة هي:

• On/Off — يفعّل نقطة النهاية أو يعطّلها.
• Test — يرسل طلب اختبار فوريًا واحدًا إلى نقطة نهاية نشطة.
• Edit — يغيّر عنوان URL أو الأحداث أو الرؤوس أو الحالة النشطة.
• Delete — يزيل إعداد نقطة النهاية نهائيًا بعد التأكيد.

حدد الجزء الرئيسي من صف لفتح Delivery history الخاصة بنقطة النهاية أسفل القائمة.

كيفية تأثير التغييرات المحفوظة في عمليات التسليم الحالية

ينشئ حدث الحساب عملية تسليم تتضمن لقطة من عنوان URL والحمولة والرؤوس المخصصة لنقطة النهاية في ذلك الوقت.

يؤثر تعديل عنوان URL أو الرؤوس المخصصة في عمليات التسليم التي تُنشأ لاحقًا. أما عملية التسليم الموجودة في قائمة الانتظار فتحافظ على وجهتها الأصلية وإعداد الرؤوس المخزن.

يؤثر تغيير الأحداث المحددة أيضًا في الأحداث التي تقع بعد ذلك فقط. ولا ينشئ Maildroppa عمليات تسليم بأثر رجعي لأنواع الأحداث التي لم تكن محددة عند وقوع الحدث.

يختلف Signing secret: إذ تتم قراءته عند إعداد طلب HTTP. لذلك يمكن لعملية تسليم معلقة أو إعادة تشغيل أن تستخدم Signing secret جديدًا تم تدويره، حتى عندما تكون حمولة العملية ولقطة نقطة النهاية قد أُنشئتا في وقت سابق.

اختبار نقطة نهاية

انقر على “Test” في نقطة نهاية نشطة بعد تجهيز المستلم وSigning secret.

يرسل Maildroppa فورًا طلبًا موقعًا واحدًا باستخدام عنوان URL المحفوظ لنقطة النهاية والرؤوس المخصصة المحفوظة. لا تدخل التغييرات غير المحفوظة في محرر مفتوح ضمن الاختبار.

تستخدم حمولة الاختبار نوع الحدث webhook.test وتعيّن livemode إلى false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

تختلف المعرّفات والطابع الزمني المُنشأ لكل اختبار فعلي.

يجري الاختبار محاولة HTTP واحدة بالضبط. ولا تُضاف عمليات تسليم الاختبار إلى جدول إعادة المحاولة الخاص بالإنتاج، ولا يمكن إعادة تشغيلها.

بعد انتهاء الطلب، تعرض لوحة النتائج:

• Test success أو Test failed
• Event ID
• حالة HTTP عند استلام استجابة
• المدة
• Delivery ID
• معلومات الخطأ عند توفرها
• مقتطفًا من الاستجابة عند إعادة المستلم لجسم

يظهر الاختبار أيضًا في Delivery history مع شارة Test. استخدم عامل التصفية “Test” لعرض طلبات الاختبار فقط.

فهم حمولة الإنتاج

تستخدم أحداث الحساب في الإنتاج غلاف JSON مشتركًا:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

تعني الخصائص ذات المستوى الأعلى ما يلي:

• id — Event ID. ويطابق X-Maildroppa-Event-Id.
• type — مفتاح الحدث المحدد في محرر نقطة النهاية.
• schema_version — إصدار مخطط الحمولة. استخدمه عند تحديد كيفية تحليل الحدث.
• created_at — وقت إنشاء حمولة الحدث، بالتوقيت العالمي المنسق UTC.
• livemode — true لأحداث الإنتاج وfalse لأحداث الاختبار.
• data — المحتوى الخاص بالحدث.

وجّه الأحداث حسب قيمة type المطابقة تمامًا. تجاهل الخصائص الإضافية التي لا يحتاجها تكاملك حتى لا تؤدي إضافات الحمولة المتوافقة إلى تعطيل المستلم.

حمولة أحداث المشترك

تحتوي أحداث المشترك على التمثيل الحالي للمشترك داخل data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields وtags مصفوفتان. ويمكن أن تكونا فارغتين. كما يمكن أن تكون خاصية المشترك null عند عدم وجود قيمة، لذلك يجب أن يتبع المستلم لديك مخطط الحمولة بدلاً من افتراض وجود كل قيمة اختيارية في الملف الشخصي.

حمولة أحداث العلامات

تحتوي أحداث العلامات على كل من المشترك والعلامة التي تسببت في الحدث:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

بالنسبة إلى subscriber.tag_removed، يظل data.tag يعرّف العلامة المُزالة رغم أن مصفوفة tags الحالية للمشترك لم تعد تتضمنها.

معرّفات الأحداث ومعرّفات التسليم وIdempotency

يؤدي Event ID وDelivery ID غرضين مختلفين.

Event ID

يعرّف Event ID الحدث التجاري. ويظهر في:

• الخاصية id ذات المستوى الأعلى في الحمولة.
• رأس الطلب X-Maildroppa-Event-Id.
• Delivery history.

يمكن إرسال الحدث نفسه إلى عدة نقاط نهاية مشتركة. وتشترك عمليات التسليم هذه في Event ID.

تحتفظ عمليات إعادة المحاولة وإعادات التشغيل اليدوية أيضًا بـ Event ID الأصلي. خزّن Event IDs التي تمت معالجتها واجعل الإجراء التجاري idempotent حتى لا يؤدي الطلب المتكرر إلى إنشاء جهات اتصال مكررة أو تكرار إجراء غير قابل للعكس أو تطبيق التغيير نفسه مرتين.

Delivery ID

يعرّف Delivery ID سجل عملية تسليم واحدة. ويظهر في:

• رأس الطلب X-Maildroppa-Delivery-Id.
• Delivery history.

لكل عملية تسليم إلى نقطة نهاية Delivery ID خاص بها. وتنشئ إعادة التشغيل اليدوية Delivery ID جديدًا مع الحفاظ على Event ID الأصلي.

استخدم Delivery ID للتتبع التقني والدعم. واستخدم Event ID لإزالة التكرار على مستوى الأعمال.

إعادة استجابة HTTP الصحيحة

يصنف Maildroppa الاستجابات كما يلي:

• أي استجابة 2xx تضع عملية التسليم في حالة نجاح.
• تُعد استجابات 408 Request Timeout و429 Too Many Requests و5xx حالات فشل مؤقتة ويمكن إعادة المحاولة.
• يُعاد محاولة حالات فشل الشبكة التي قد تكون مؤقتة.
• لا تُتبع عمليات إعادة التوجيه والاستجابات الأخرى من فئة 3xx، وتُعامل كحالات فشل نهائية.
• تُعامل استجابات 4xx الأخرى كحالات فشل نهائية ولا يُعاد محاولة إرسالها.

أعد 200 أو 202 أو 204 فقط عندما يكون الحدث قد قُبل بأمان. وإذا استغرقت المعالجة وقتًا، فخزّن الحدث أولًا وأعد استجابة نجاح قبل تنفيذ العمل الأبطأ بشكل غير متزامن.

لا تُعد توجيهًا إلى عنوان URL آخر لـ Webhook. اضبط عنوان URL النهائي في Maildroppa بدلاً من ذلك.

جدول إعادة المحاولة التلقائية

يمكن لعمليات تسليم الإنتاج إجراء ما يصل إلى سبع محاولات HTTP.

بعد فشل قابل لإعادة المحاولة، يجدول Maildroppa المحاولة التالية وفق التأخيرات التالية:

1. بعد المحاولة 1: دقيقة واحدة
2. بعد المحاولة 2: 5 دقائق
3. بعد المحاولة 3: 30 دقيقة
4. بعد المحاولة 4: ساعتان
5. بعد المحاولة 5: 12 ساعة
6. بعد المحاولة 6: 24 ساعة

إذا استمرت المحاولة 7 في تلقي فشل قابل لإعادة المحاولة، تصبح عملية التسليم Dead ولا تتم جدولة أي محاولة تلقائية أخرى.

يُقاس الجدول انطلاقًا من محاولات الفشل الفردية. وقد يتأخر وقت التسليم الفعلي قليلًا لأن عمليات التسليم تُعالج بشكل غير متزامن وتخضع أيضًا لحدود حماية النظام.

أصلح مشكلة المستلم المؤقتة قبل وقت “Next retry” المعروض كلما أمكن. وإذا انتهت المحاولات التلقائية، فاستخدم Replay بعد عودة المستلم إلى حالته السليمة.

فهم Delivery history

ينتمي Delivery history إلى نقطة النهاية المحددة حاليًا. ويظهر عنوان URL لنقطة النهاية في عنوان القسم حتى تتمكن من تأكيد السجل الذي تعرضه.

استخدم عوامل التصفية التالية:

• All — يعرض عمليات تسليم الإنتاج والاختبار.
• Production — يعرض عمليات تسليم الأحداث المباشرة فقط.
• Test — يعرض الاختبارات اليدوية فقط.

انقر على “Refresh” لاسترجاع أحدث حالة. لا يلزم إبقاء السجل مفتوحًا أثناء إرسال Maildroppa لعملية تسليم أو إعادة محاولتها.

تعرض الصفحة أحدث 50 عملية تسليم مطابقة لعامل التصفية المحدد.

أعمدة التسليم

يحتوي كل صف على:

• Created — وقت إنشاء سجل التسليم.
• State — Pending أو Success أو Failed أو Dead.
• HTTP — حالة الاستجابة وعدد المحاولات والمدة ووقت إعادة المحاولة التالية عند انطباق ذلك.
• Subscriber — بريد المشترك الإلكتروني عندما يكون الحدث مرتبطًا بمشترك.
• Delivery — نوع الحدث وEvent ID وDelivery ID.
• Actions — Replay عندما تكون عملية التسليم مؤهلة.

إذا لم يُجرَ أي طلب HTTP، يعرض عمود HTTP عبارة “No HTTP attempt”. وقد يحدث ذلك عندما يرفض Maildroppa الطلب قبل الإرسال، مثلًا بسبب غياب Signing secret أو تعذر استخدام الوجهة المحفوظة بأمان.

عند توفرها، يعرض الصف أيضًا Error وResponse excerpt اللذين أعادهما المستلم. لا تُعد أسرارًا أو بيانات شخصية حساسة في جسم استجابة Webhook، لأن جزءًا من تلك الاستجابة قد يظهر في سجل التسليم الخاص بالحساب.

حالات التسليم

تعني Pending أن عملية التسليم تنتظر المحاولة الأولى أو إعادة محاولة مجدولة. يظهر “Next retry” عند جدولة محاولة أخرى.

تعني Success أن المستلم أعاد استجابة 2xx. ولا حاجة إلى مزيد من المحاولات التلقائية.

تعني Failed أن عملية التسليم انتهت بمشكلة غير قابلة لإعادة المحاولة، أو رُفضت قبل محاولة HTTP، أو أُوقفت قبل إرسالها.

تعني Dead استخدام جميع المحاولات التلقائية لمشكلة قابلة لإعادة المحاولة دون استلام استجابة ناجحة.

الاحتفاظ بالسجل

يتم الاحتفاظ بسجلات التسليم لفترة محدودة:

• عمليات تسليم الإنتاج الناجحة: 30 يومًا
• عمليات تسليم الإنتاج الفاشلة: 90 يومًا
• عمليات تسليم الإنتاج Dead: 90 يومًا
• عمليات تسليم الاختبار: 30 يومًا

احتفظ بسجلات التكامل الخاصة بك عندما تحتاج إلى سجل تدقيق أطول. خزّن Event IDs وDelivery IDs، وتجنب تخزين الأسرار دون ضرورة.

إعادة تشغيل عملية تسليم

انقر على “Replay” عندما يجب محاولة إرسال عملية تسليم إنتاج مكتملة مرة أخرى.

يتوفر Replay لعمليات تسليم الإنتاج في حالات Success أو Failed أو Dead. ولا يتوفر أثناء كون عملية التسليم Pending، كما لا يمكن إعادة تشغيل عمليات تسليم الاختبار.

تؤدي إعادة التشغيل إلى:

• إنشاء عملية تسليم Pending جديدة.
• إنشاء Delivery ID جديد.
• الاحتفاظ بـ Event ID الأصلي.
• الاحتفاظ بنوع الحدث الأصلي وحمولة JSON الأصلية.
• استخدام عنوان URL الأصلي المحفوظ للهدف ولقطة الرؤوس المخصصة.
• استخدام Signing secret الحالي عند إعداد الطلب الجديد.

لا تعيد Replay بناء الحمولة من بيانات المشترك الحالية. بل يعيد إرسال لقطة الحدث الأصلية. يجعل ذلك إعادة التشغيل قابلة للتدقيق ويمنع تغير معنى حدث تاريخي دون إشعار.

يمكن أن تكون إعادة تشغيل واحدة فقط من عملية التسليم المصدر نفسها في حالة Pending في كل مرة. انتظر حتى تنتهي إعادة التشغيل قبل طلب أخرى.

تأكد من أن نقطة النهاية Active قبل إعادة التشغيل. وإذا كانت غير نشطة، فلن يمكن تسليم إعادة التشغيل الموضوعة في قائمة الانتظار بنجاح.

لأن المستلم قد يكون أكمل الإجراء التجاري حتى عندما لم يتلق Maildroppa استجابة النجاح، فقد تؤدي إعادة التشغيل إلى طلب مكرر. تحمي إزالة التكرار باستخدام Event ID النظام المتصل من تكرار الإجراء.

تعديل نقطة نهاية

انقر على “Edit” لتغيير عنوان URL أو اختيار الأحداث أو الرؤوس المخصصة أو الحالة النشطة.

قبل الحفظ:

1. تأكد من أن عنوان URL الجديد متاح بالفعل.
2. اترك قيم الرؤوس المخزنة فارغة عندما يجب أن تبقى دون تغيير.
3. أدخل قيمة جديدة لكل رأس تمت إعادة تسميته.
4. راجع اختيار الأحداث حتى لا تتم إزالة الإشعارات المطلوبة عن طريق الخطأ.
5. احفظ وأرسل Test webhook جديدًا.

تذكر أن عمليات التسليم الموضوعة في قائمة الانتظار تحتفظ بلقطة عنوان URL والرؤوس المخصصة الحالية. اختبر الإعداد الجديد لعمليات التسليم المستقبلية بدلاً من افتراض أنه يغير طلبًا أقدم في قائمة الانتظار.

إلغاء تنشيط نقطة نهاية

استخدم مفتاح On/Off عندما تريد إيقاف التكامل مؤقتًا دون حذف إعداداته وسجله.

عند إيقاف نقطة النهاية:

• لا تُضاف الأحداث الجديدة إلى قائمة الانتظار لها.
• تُعلَّم عمليات التسليم Pending التي لم تتم المطالبة بها للإرسال بعد بحالة Failed.
• يتم تعطيل Test.
• تظل نقطة النهاية متاحة للتحرير والتفعيل لاحقًا.

يمكن أن يكتمل الطلب الجاري بالفعل وقت إلغاء التنشيط. تحقق من Delivery history بعد إيقاف نقطة النهاية إذا كان هذا الفرق مهمًا لتكاملك.

لا تتم إضافة الأحداث التي فاتت أثناء عدم نشاط نقطة النهاية عند تشغيلها مرة أخرى.

حذف نقطة نهاية

انقر على “Delete” وأكد التحذير عندما لا تعود نقطة النهاية مطلوبة.

يؤدي الحذف إلى إزالة نقطة النهاية من الصفحة، وإيقاف عمليات تسليم الأحداث المستقبلية، ووضع عمليات التسليم Pending التي لم تتم المطالبة بها للإرسال بعد في حالة Failed.

لا يُعد Delete وسيلة للإيقاف المؤقت. استخدم مفتاح On/Off عندما قد تحتاج إلى الإعداد أو السجل الظاهر مرة أخرى.

قبل الحذف، سجّل أي Event IDs أو Delivery IDs ما زلت تحتاج إليها لتدقيق التكامل.

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

يتعذر حفظ نقطة النهاية

تحقق من أن:

• عنوان URL يبدأ بـ https://.
• عنوان URL يستخدم اسم مضيف عامًا ومنفذ 443.
• لا يحتوي عنوان URL على متغيرات أو معلومات تسجيل دخول أو جزء لاحق.
• تم تحديد حدث واحد على الأقل.
• لكل Custom header اسم فريد وقيمة.
• لم تُستخدم رؤوس Maildroppa وHTTP المحجوزة كأسماء مخصصة.

Test معطل

يتوفر Test فقط لنقطة نهاية Active. شغّل نقطة النهاية أو حررها وحدد “Active”، ثم احفظ قبل الاختبار.

لا يعرض Test أي محاولة HTTP

أنشئ Signing secret إذا كانت الحالة Missing. وتحقق أيضًا من أن اسم مضيف الوجهة عام ولا يزال يُحل بشكل صحيح.

قد يُرفض الطلب قبل الإرسال عندما يكون السر أو عنوان URL أو الرؤوس المخصصة أو فحص أمان الوجهة غير صالح.

يعيد المستلم 401 أو 403

تحقق من اسم Custom header المحفوظ وبيانات الاعتماد. حرر نقطة النهاية وأدخل القيمة مرة أخرى إذا تغيرت.

تحقق أيضًا من أن المستلم لا يخلط بين بيانات اعتماد API الخاصة به وتوقيع Maildroppa. يؤدي رأس تفويض مخصص وX-Maildroppa-Signature غرضين مختلفين ويمكن فحصهما بشكل مستقل.

يعيد المستلم إعادة توجيه

لا يتبع Maildroppa عمليات إعادة التوجيه. استبدل عنوان URL لنقطة النهاية بعنوان URL العام النهائي الذي يستخدم HTTPS، ثم اختبر مرة أخرى.

لا يتطابق التوقيع

تأكد من أن المستلم:

• يستخدم Signing secret الحالي.
• يستخدم قيمة X-Maildroppa-Timestamp كما هي تمامًا.
• يوقّع <timestamp>.<raw request body>.
• يستخدم HMAC-SHA256 ومخرجًا سداسيًا عشريًا بأحرف صغيرة.
• يقارن القيمة الكاملة بما في ذلك v1=.
• يجري المقارنة قبل أن يؤدي تحليل JSON إلى تغيير الجسم.

يصل الحدث نفسه أكثر من مرة

قد يحدث ذلك بعد انقطاع في الشبكة أو إعادة محاولة أو Replay يدوي. من الطبيعي أن توفر أنظمة تسليم Webhook تسليمًا «مرة واحدة على الأقل» بدلاً من تسليم «مرة واحدة بالضبط».

استخدم Event ID كمفتاح idempotency. أعد استجابة 2xx عند استلام Event ID سبق معالجته ولا تكون هناك حاجة إلى إجراء إضافي.

عملية التسليم Pending

راجع “Next retry” في عمود HTTP. تبقى حالات 408 أو 429 أو 5xx القابلة لإعادة المحاولة، أو حالات فشل الشبكة المؤقتة، في حالة Pending حتى المحاولة المجدولة التالية.

انقر على “Refresh” بعد وقت إعادة المحاولة لتحميل أحدث حالة.

عملية التسليم Dead

تم استخدام جميع المحاولات التلقائية. أصلح المستلم أولًا، وتأكد من أن نقطة النهاية Active، وأرسل Test webhook، ثم استخدم Replay في عملية تسليم الإنتاج.

قائمة التحقق الموصى بها للإنتاج

قبل الاعتماد على نقطة نهاية في الإنتاج، تأكد من كل ما يلي:

1. يستخدم المستلم عنوان HTTPS عامًا مستقرًا مع شهادة صالحة.
2. يتم تخزين Signing secret خارج التعليمات البرمجية المصدرية.
3. يتم التحقق من التوقيع مقابل الجسم الخام غير المعدّل.
4. يتم رفض الطوابع الزمنية القديمة وفق مهلة موثقة.
5. يخزّن المستلم Event IDs ويزيل تكرارها.
6. يسجل المستلم Event IDs وDelivery IDs لأغراض التتبع.
7. تتم المعالجة البطيئة بعد قبول الحدث بشكل دائم.
8. تتم إعادة استجابة 2xx فقط للأحداث المقبولة.
9. تُخزّن بيانات الاعتماد المخصصة في الرؤوس بدلاً من عنوان URL.
10. يتم تحديد أنواع الأحداث المطلوبة فقط.
11. ينجح Test webhook ويظهر بشكل صحيح في Delivery history.
12. تنبهك المراقبة عند بدء عمليات تسليم الإنتاج في إعادة الأخطاء.

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