Webhooks

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

كيف تعمل webhooks

سجّل نقطة نهاية HTTPS في لوحة التحكم واختر الأحداث التي تريد استقبالها. عند حدوث شيء لرسالة، يرسل MigoSMTP طلب POST بجسم JSON إلى نقطة نهايتك.

أنواع الأحداث

اشترك فقط في الأحداث التي يحتاجها نظامك. يحمل كل حدث معرّف الرسالة والمستلم والطابع الزمني، فيمكنك مطابقته مع الرسالة التي أرسلتها.

حمولة نموذجية

الحمولات بصيغة JSON وتُرسل بطلب POST. القيم هنا للتوضيح فقط.

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

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

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

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

استجب بسرعة

أعد حالة 2xx فور تخزين الحدث، ونفّذ العمل الفعلي لاحقًا عبر طابور. نقطة النهاية البطيئة أو الفاشلة تسبب إعادة المحاولات وقد تؤخر أحداثك الأخرى.

توقّع التكرار واختلاف الترتيب

تُعاد محاولة عمليات التسليم الفاشلة، فقد يصل الحدث نفسه أكثر من مرة، وقد تصل الأحداث بغير ترتيبها. استخدم معرّف الرسالة ونوع الحدث لجعل معالجك idempotent، واعتمد الطابع الزمني للحدث لا وقت وصوله.

اختبر قبل أن تعتمد عليه

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