كل المقالات
الهندسة

Webhooks: الأحداث والتوقيعات وإعادة المحاولة

ما الأحداث التي يرسلها Postline، وكيف تتحقق من كل طلب، وماذا يحدث عند تعطل نقطتك.

الأحداث

اشترك لكل نقطة في 1 إلى 20 من أنواع الأحداث التالية:

  • email.accepted
  • email.queued
  • email.sent
  • email.delivered
  • email.deferred
  • email.bounced
  • email.complained
  • email.opened
  • email.clicked
  • email.received
  • email.suppressed
  • domain.verified
  • domain.failed

مدخلات التوقيع

HMAC-SHA256(secret, timestamp + "\0" + event_id + "\0" + body)

Postline-Timestamp: 1784743200
Postline-Event-Id: evt_…
Postline-Signature: v1=…

الطلب والمحتوى

POST https://example.com/hooks/postline
Content-Type: application/json
Postline-Event-Id: evt_3f2a9c…
Postline-Timestamp: 1784743200
Postline-Signature: v1=5d41402abc4b2a76…

{
  "id": "evt_3f2a9c…",
  "type": "email.delivered",
  "created_at": "2026-11-05T12:00:00Z",
  "data": {
    "email_id": "msg_01J…",
    "recipient": "user@example.net",
    "provider": "gmail",
    "smtp_response": "250 2.0.0 OK"
  }
}

متطلبات المستقبِل

  • احسب التوقيع من نص الطلب الخام (raw) الدقيق.
  • قارن التوقيعات بزمن ثابت (constant time).
  • ارفض الطوابع الزمنية خارج النافذة المسموح بها.
  • احفظ event_id وعالج كل حدث مرة واحدة فقط.
  • لا تفترض وصول الأحداث بترتيب دورة الحياة.

ضوابط الاتصال الصادر

يتطلب إنشاء نقطة النهاية استخدام HTTPS. تُحظر الوجهات الخاصة وloopback وlink-local وmetadata والوجهات الحاملة لبيانات اعتماد أو الداخلية، ويُعاد تحليلها (resolve) وقت الاتصال أيضًا. لا يتم اتباع عمليات إعادة التوجيه (redirects). يستخدم التسليم مهلات محدودة وعددًا محدودًا من محاولات إعادة المحاولة.

المهلات وإعادة المحاولة

أي استجابة 2xx تؤكد الحدث. انتهاء المهلة (15 ثانية) أو خطأ الشبكة أو أي حالة أخرى تُعد فشلًا. يجري Postline حتى 6 محاولات: الأولى ثم بعد 1 د و5 د و30 د وساعتين و8 ساعات. تُسجَّل كل محاولة في سجل التسليم ويمكن إعادة أي تسليم يدويًا عبر API أو لوحة التحكم.