نظرة عامة على Webhooks

تُرسل Webhooks إشعارات HTTP فورية إلى خادمك عند وقوع أحداث البريد الإلكتروني، التسليم، والارتداد، والشكاوى، وغير ذلك. بدلاً من الاستعلام المتكرر عن تغييرات الحالة، تُرسل MailLand الأحداث إلى endpoint الخاص بك فور وقوعها.

كيف تعمل Webhooksنسخ رابط القسم

إنشاء Webhookنسخ رابط القسم

POST https://api.mail.land/v1/webhooks

curl -X POST https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains"
  }'

حقول الطلبنسخ رابط القسم

الاستجابةنسخ رابط القسم

الحالة: 201 Created

{
  "webhook": {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "includeFutureEvents": true,
    "scope": "all_domains",
    "domainIds": [],
    "isActive": true,
    "createdAt": "2026-02-17T10:00:00Z",
    "successCount": 0,
    "failureCount": 0,
    "consecutiveFailures": 0,
    "pauseThreshold": 10
  },
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
}

قائمة Webhooksنسخ رابط القسم

GET https://api.mail.land/v1/webhooks

curl -X GET https://api.mail.land/v1/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "id": "k3m9x2p7qw4rtz",
    "name": "Production Events",
    "webhookUrl": "https://your-app.com/webhooks/mailland",
    "products": ["transactional", "marketing"],
    "events": ["message.delivered", "message.bounced"],
    "isActive": true,
    "lastTriggeredAt": "2026-02-17T12:30:00Z",
    "lastSuccessAt": "2026-02-17T12:30:00Z",
    "successCount": 1542,
    "failureCount": 3,
    "consecutiveFailures": 0,
    "createdAt": "2026-02-10T08:00:00Z"
  }
]

يُرجع ما يصل إلى 100 webhook مرتبة حسب تاريخ الإنشاء (الأحدث أولاً).

عرض تفاصيل Webhookنسخ رابط القسم

GET https://api.mail.land/v1/webhooks/{id}

curl -X GET https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يُرجع التهيئة الكاملة للـ webhook بالإضافة إلى أحدث 50 سجل تسليم. راجع منطق إعادة المحاولة للاطلاع على تفاصيل سجلات التسليم.

تحديث Webhookنسخ رابط القسم

PUT https://api.mail.land/v1/webhooks/{id}

curl -X PUT https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "All Events",
    "events": ["message.delivered", "message.bounced", "message.deferred", "message.complained"],
    "isActive": true
  }'

جميع الحقول اختيارية: أدرج فقط الحقول التي تريد تغييرها.

اختبار Webhookنسخ رابط القسم

أرسل حدثاً تجريبياً للتحقق من أن endpoint الخاص بك يعمل:

POST https://api.mail.land/v1/webhooks/{id}/test

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "success": true,
  "statusCode": 200,
  "statusText": "OK",
  "durationMs": 145,
  "responseBody": "{\"received\": true}",
  "headersSent": {
    "X-MLND-Signature": "t=1708171200,v1=abc123...",
    "X-MLND-Event-Id": "evt_test_abc123",
    "X-MLND-Event-Version": "1",
    "X-MLND-Event": "webhook.test",
    "X-MLND-Webhook-Id": "k3m9x2p7qw4rtz",
    "X-MLND-Attempt": "1"
  },
  "wouldReceiveRealEvents": true,
  "liveEvents": ["message.delivered", "message.bounced"],
  "dormantEvents": {},
  "subscriptionWarning": null
}

يستخدم إرسال الاختبار التوقيع نفسه ومسار التسليم نفسه المستخدمين مع الحدث الحقيقي، لذا يثبت نجاحه هنا صحة عنوانك وبروتوكول TLS والتحقق من توقيعك.

لكنه لا يثبت اشتراكك: يُرسل الاختبار عند الطلب ولا يُوجَّه بحسب الأحداث التي اخترتها. تجيب الحقول الأربعة الأخيرة عن ذلك على حدة:

الحالة المهمة هي "success": true مع "wouldReceiveRealEvents": false: نقطة النهاية تعمل لكنها غير مشترِكة في أي شيء يمكن تسليمه.

إذا فشل الاختبار، يُشير حقل errorType إلى السبب: ssrf_blocked (أشار العنوان، أو إعادة توجيه منه، إلى وجهة ترفض المنصة الإرسال إليها) أو network_error (انتهاء المهلة أو فشل TLS أو رفض الاتصال؛ ويحمل errorMessage التفاصيل).

إعادة توليد السرنسخ رابط القسم

إذا فقدت سر الـ webhook أو احتجت إلى تدويره:

POST https://api.mail.land/v1/webhooks/{id}/regenerate-secret

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/regenerate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "secretKey": "whsec_x9y8z7w6v5u4..."
}

نطاق النطاقنسخ رابط القسم

افتراضياً، تتلقى webhooks الأحداث لجميع النطاقات في مساحة العمل الخاصة بك. لتقييد webhook بنطاقات محددة:

{
  "webhookUrl": "https://your-app.com/webhooks/mailland",
  "scope": "selected_domains",
  "domainIds": ["d4n8q1zt5wm3xc", "b7r2mv9k0jy4pw"]
}

ستُشغّل webhook فقط الأحداث المتعلقة بتلك النطاقات.

الإيقاف المؤقت التلقائي عند حدوث أعطالنسخ رابط القسم

تُوقف MailLand Webhooks تلقائياً بعد 10 أعطال متتالية في التسليم (قابل للتهيئة عبر pauseThreshold). يمنع ذلك إهدار الموارد على endpoints المعطّلة.

عند إيقاف webhook مؤقتاً:

• يُعيَّن الطابع الزمني pausedAt
• يصف pausedReason سبب الإيقاف المؤقت
• يُرسَل حدث account.webhook_paused إلى webhooks الأخرى النشطة لديك
• يُنشأ إشعار داخل التطبيق

استئناف Webhook موقوف مؤقتاًنسخ رابط القسم

بعد إصلاح المشكلة، استأنف التسليم:

POST https://api.mail.land/v1/webhooks/{id}/resume

curl -X POST https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz/resume \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يمسح هذا الأمر حالة الإيقاف المؤقت، ويُعيد تعيين عداد الأعطال المتتالية، ويُعيد تفعيل الـ webhook (تصبح isActive قيمتها true من جديد)، بحيث تُسلَّم الأحداث المستقبلية إليه بشكل طبيعي.

حذف Webhookنسخ رابط القسم

DELETE https://api.mail.land/v1/webhooks/{id}

curl -X DELETE https://api.mail.land/v1/webhooks/k3m9x2p7qw4rtz \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يُرجع 204 No Content. إذا كان الـ webhook مستخدماً من قِبل مسارات البريد الوارد، فسيتم تحديث تلك المسارات أو تعطيلها تلقائياً.

ردود الأخطاءنسخ رابط القسم

الخطوات التاليةنسخ رابط القسم

• الأحداث: مرجع كامل لجميع أنواع الأحداث والبيانات
• التحقق من التوقيع: التحقق من أصالة الـ webhook
• منطق إعادة المحاولة: فهم سلوك إعادة المحاولة ومعالجة الأعطال