الـ Webhooks والأحداث
نتائج التسليم تصل إلى تطبيقك
يرسل Mail.Land حدثًا موقّعًا إلى نقطة النهاية لديك عند تسليم رسالة أو تأجيلها أو ارتدادها أو انتهائها بالفشل، وعند شكوى المستلم، وعند وصول بريد وارد، مع سجل لكل محاولة.
import crypto from "node:crypto";
// header: X-MLND-Signature: t=1708171200,v1=<hex>
export function verify(rawBody, header, secret) {
if (typeof header !== "string" || header === "") return false;
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (!parts.t || !parts.v1 || age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}الأحداث التي يمكنك الاشتراك فيها اليوم
ثمانية أنواع من الأحداث مفعّلة. اشترك فيها كلها أو فيما تحتاجه فقط.
| يُرسل عندما | |
|---|---|
| message.delivered | يقبل خادم بريد المستلم الرسالة |
| message.deferred | يتأخر التسليم مؤقتًا، ويواصل Mail.Land المحاولة |
| message.bounced | يرفض خادم المستلم الرسالة، مع نوع الارتداد ورد الخادم |
| message.failed | يعلّم Mail.Land الرسالة فاشلةً لسبب داخلي أو بموجب سياسة؛ ولا يضيف هذا الحدث المستلم إلى قائمة منع الإرسال |
| message.complained | يبلّغ المستلم عن الرسالة بوصفها بريدًا عشوائيًا عبر حلقة الملاحظات |
| message.outcome_unknown | لم يتمكن Mail.Land بعد من معرفة ما إذا كانت الرسالة قد وصلت إلى طابور التسليم؛ ويتبعه حدث نهائي إذا عرف Mail.Land النتيجة لاحقًا |
| message.retried | تعيد إرسال رسالة مرتدة أو فاشلة فتعود إلى الطابور |
| inbound.received | تصل رسالة إلى أحد نطاقاتك وتطابق مسار webhook |
أنواع الأحداث الأخرى، مثل message.sent وفتح الرسائل والنقرات، مدرجة في الفهرس للمستقبل ولا تُرسل بعد. وتوضح نقطة نهاية الفهرس المتاح منها الآن.
موقّع، ولا يُرسل إلا إلى حيث يجب
يمكن التحقق من كل طلب، ويرفض Mail.Land الوجهات التي قد يُساء استخدامها.
HMAC-SHA256 مع طابع زمني
تحمل ترويسة X-MLND-Signature طابعًا زمنيًا وتوقيعًا لهذا الطابع مع النص الخام. تحقق منه بمقارنة ثابتة الزمن، وارفض الطوابع القديمة لمنع إعادة تشغيل الطلبات.
HTTPS على المنفذ 443 فقط
تُرفض العناوين الخاصة وعناوين loopback. وتُتبع عمليات إعادة التوجيه ثلاث قفزات على الأكثر، ويُعاد فحص كل قفزة قبل إرسال أي شيء إليها.
سرّ واحد لكل webhook
يظهر سرّ التوقيع مرة واحدة عند إنشاء الـ webhook. وإذا تسرب، فأنشئ سرًا جديدًا: يتوقف القديم عن العمل فورًا.
عندما تكون نقطة النهاية متوقفة
يُعاد تسليم الحدث الفاشل افتراضيًا وفق هذا الجدول. ويُعد الرد 2xx خلال 15 ثانية نجاحًا.
| الانتظار قبل المحاولة | الوقت منذ المحاولة الأولى | |
|---|---|---|
| المحاولة 1 | لا انتظار | 0 |
| المحاولة 2 | فورًا | نحو 0 |
| المحاولة 3 | دقيقة واحدة | نحو دقيقة |
| المحاولة 4 | 5 دقائق | نحو 6 دقائق |
| المحاولة 5 | 15 دقيقة | نحو 21 دقيقة |
| المحاولة 6 | ساعة واحدة | نحو ساعة و21 دقيقة |
يُعاد المحاولة عند انتهاء المهلة وأخطاء الشبكة والردود 408 و429 و500 و502 و503 و504، وتحدد ترويسة Retry-After مدة الانتظار التالية. أما الردود الأخرى خارج 2xx فنهائية. ويمكنك إعادة أي تسليم فاشل من السجل.
مصمم لأحداث تصل متأخرة أو مرتين
التسليم يتم مرة واحدة على الأقل وليس دائمًا بالترتيب. ويحمل كل حدث ما تحتاجه للتعامل مع ذلك.
إصدارات الحالة
يحمل كل حدث رسالة رقم إصدار للحالة يرتفع مع كل تغيير. إذا اشتركت في كل أحداث الرسائل وطبّقت الحدث فقط عندما يكون إصداره أعلى من المخزّن لديك، تبقى الحالة صحيحة مهما كان ترتيب الوصول. ومع عدد أقل من الأحداث، تحقق من الحالة الحالية عبر الواجهة.
معرّفات أحداث ثابتة
معرّف الحدث هو نفسه في كل إعادة محاولة. احفظ المعرّفات التي عالجتها وتجاهل التكرار.
حمولات بإصدارات
لكل نوع حدث إصدار مخطط. ولا يضيف Mail.Land إلى إصدار قائم إلا حقولًا وترويسات، فيستمر في العمل المستقبِل الذي يتجاهل الحقول غير المعروفة.
التحكم والوضوح
أدر الـ webhooks من لوحة التحكم أو عبر الواجهة.
التصفية بحسب المنتج والنطاق
اختر أحداث البريد التعاملي أو التسويقي أو الوارد، وأنواع أحداث بعينها، وكل النطاقات أو بعضها فقط.
اختبر قبل الاعتماد عليه
أرسل حدثًا تجريبيًا بالتوقيع والنقل الحقيقيين. ويخبرك الرد أيضًا ما إذا كانت الأحداث الحقيقية تستطيع الوصول إلى نقطة النهاية باشتراكها الحالي.
سجل التسليم
اطّلع على كل محاولة وحالتها، وصفِّ المحاولات الفاشلة، وأعد تسليمًا يدويًا.
إيقاف مؤقت تلقائي
افتراضيًا، بعد 10 محاولات فاشلة متتالية يتوقف الـ webhook مؤقتًا وتتلقى إشعارًا في لوحة التحكم. استأنفه عندما تعود نقطة النهاية إلى العمل.
أسئلة عن الـ Webhooks
هل يوجد حدث عند قبول الرسالة أو إرسالها؟
ليس بعد. الحدث message.sent موجود في الفهرس لكنه لا يُرسل اليوم. يحمل رد الواجهة على طلب الإرسال معرّفات الرسائل، وأول حدث webhook تتلقاه هو نتيجة التسليم.
هل يمكنني تلقي أحداث الفتح والنقر؟
ليس عبر webhook اليوم. تظهر عمليات الفتح والنقر، حيث يكون التتبع مفعّلًا، في سجلاتك وتحليلاتك؛ أما أحداثها فمدرجة في الفهرس لوقت لاحق.
ماذا لو ارتدت رسالة سُلّمت من قبل؟
قد يحدث ذلك: فخادم الاستلام قد يرفض رسالة بعد قبولها. عندها يرسل Mail.Land حدث ارتداد بإصدار حالة أعلى، لذا واصل معالجة الأحداث بعد حدث التسليم.
ماذا يحدث إذا توقفت نقطة النهاية يومًا كاملًا؟
يُحاول تسليم كل حدث افتراضيًا حتى ست مرات على مدى 80 دقيقة تقريبًا، ويتوقف الـ webhook مؤقتًا بعد 10 محاولات فاشلة متتالية افتراضيًا. وخلال التوقف لا تُوضع له أحداث جديدة في الطابور. بعد استئنافه، أعد عمليات التسليم الفاشلة من السجل، وتحقق من حالة الرسائل عبر الواجهة، وأعد إرسال الرسائل الواردة التي فاتتك.
كيف أتحقق من أن الطلب جاء من Mail.Land؟
احسب HMAC-SHA256 على الطابع الزمني ونقطة والنص الخام بسرّ الـ webhook، وقارنه بالقيمة v1 مقارنة ثابتة الزمن، وارفض الطوابع الأقدم من 5 دقائق. وفي الوثائق مثال بقيم دقيقة.
هل يمكن لنقطة نهاية أن تتلقى أحداث بعض نطاقاتي فقط؟
نعم. اضبط نطاق الـ webhook على نطاقات محددة واذكرها؛ فلا يتلقى بعدها إلا أحداث تلك النطاقات.
اربط تطبيقك بنتيجة كل عملية تسليم
أنشئ حسابًا مجانيًا، وأضف نقطة نهاية، وأرسل إليها حدثًا تجريبيًا.