الإجابة المختصرة
لاستقبال تقارير التسليم عبر Webhook، جهّز نقطة استقبال HTTPS تقبل طلبات POST وسجّل عنوانها لدى مزوّد المراسلة. خزّن كل حدث، وردّ بسرعة برمز حالة 2xx، ثم عالجه بشكل غير متزامن. اربط الأحداث بسجلاتك عبر معرّف الرسالة، وأزل المكرر منها، ولا تسمح أبداً لحالة متأخرة بأن تحل محل حالة نهائية.
إعداد نقطة الاستقبال
أثناء التطوير، يمنح النفق (tunnel) الخادم المحلي عنوان HTTPS عاماً.
- جهّز نقطة استقبال HTTPS تقبل طلبات POST بجسم JSON.
- زوّد المزوّد بعنوان URL ليُضبط على الحساب أو الحساب الفرعي الصحيح.
- أرسل رسالة تجريبية إلى رقمك وسجّل جسم الحدث الخام.
- حدّد الحقول التي تحتاجها من أحداث فعلية، لا من أسماء حقول مفترضة.
- احتفظ بنماذج من الحمولات كبيانات اختبار لكل قناة تستخدمها.
ما الحالات التي ستصلك؟
يحوّل المزوّدون تقارير المشغلين والقنوات إلى أسماء حالات خاصة بهم. وهذه المجموعة الموحّدة هي التي تستخدمها OmniChannels.ai عبر SMS وWhatsApp والقنوات الأخرى.
| الحالة | المعنى | نهائية؟ |
|---|---|---|
| SUBMITTED | قُبلت ووُضعت في قائمة الانتظار | لا |
| SENT | سُلّمت إلى المشغل أو القناة | لا |
| DELIVERED | تأكد وصولها إلى الجهاز | غالباً، وقد تليها READ |
| READ | فُتحت، في القنوات التي تُبلغ بالقراءة | نعم |
| FAILED | لم تُسلَّم، مع ذكر السبب إن توفر | نعم |
| REJECTED | رُفضت، مثلاً بسبب اسم مرسل غير مسجّل | نعم |
اجعل المعالج موثوقاً
- خزّن الجسم الخام ثم أعد 2xx. وإذا فشل التخزين فأعد 5xx ليُعاد إرسال الحدث.
- نفّذ المعالجة الفعلية في قائمة انتظار أو عامل خلفي، لا قبل الرد.
- أزل المكرر بحسب معرّف الرسالة، فقد تصل الحالة نفسها مرتين.
- رتّب الحالات بحيث لا تحل SENT المتأخرة محل DELIVERED أبداً.
- اقبل قيم الحالات التي لا تعرفها بدلاً من الفشل.
- لا تُعِد إرسال أي رسالة من داخل معالج الـ Webhook.
التأمين واسترداد التقارير الفائتة
اقبل HTTPS فقط، واستخدم مساراً طويلاً يصعب تخمينه، وتحقق من بنية الجسم، وتأكد من الحالة باستدعاء استعلام قبل أي إجراء لا رجعة فيه مثل الاسترداد المالي. وإذا كانت نقطة الاستقبال متوقفة، فاطلب من المزوّد إعادة إرسال التقارير لتلك الفترة أو اقرأ الحالات من نقاط التقارير لديه.
في SMPP تصل التقارير على شكل deliver_sm عبر الـ bind بدلاً من Webhook. وبعض المشغلين يعيدون التقارير متأخرة أو لا يعيدونها إطلاقاً، لذا تعامل معها كدليل قوي لا كإثبات على القراءة.