تخطَّ إلى المحتوى الرئيسي

Webhooks

سجّل نقطة استقبال ويب هوك لتلقي أحداث لحظية للمصادقة والتسليم والردود.

4 دقيقة قراءة

تتيح لك الـ Webhooks استقبال أحداث من Mersal في الوقت الفعلي، بدلاً من الاستعلام المتكرر عن نقاط GET /api/get/{channel}/{id?} لمعرفة الحالة. سجّل نقطة استقبال على خادمك الخاص مرة واحدة، وستدفع Mersal الأحداث إليها فور حدوثها.

مرسال يستدعي سيرفرك بحمولة JSON عند كل حدث تشترك فيه

كيف تصل حالة التسليم إلى Mersal

خلف الكواليس، تستقبل Mersal تحديثات التسليم والحالة من عدة مصادر: webhooks واردة من مزودي البريد الإلكتروني (SendGrid وAmazon SES وMailgun وMailjet) لأحداث الارتداد والتسليم، وwebhook خاص بـ WhatsApp Cloud API، وwebhook بوابة WhatsApp المبنية على Node الخاصة بـ Mersal للأجهزة المتصلة عبر QR. هذه الـ webhooks الداخلية هي الطريقة التي تعرف بها Mersal نفسها أن رسالة ما تم تسليمها أو ارتدت أو تم الرد عليها — لست بحاجة لإعدادها أو التعامل معها مباشرة.

ما يهمك كمطوّر متكامل مع المنصة هو الويب هوك الموجّه للعميل الموضح أدناه: وهو الذي تستدعيه Mersal على خادمك بعد معالجتها لتلك الأحداث الداخلية.

تسجيل نقطة استقبال ويب هوك

يتم تسجيل الويب هوك من لوحة التحكم وليس عبر استدعاء API. اذهب إلى Automation ← Webhooks وأضف رابط نقطة الاستقبال الخاصة بك. من هناك يمكنك:

  • تسجيل رابط نقطة استقبال ستستدعيه Mersal عند حدوث الأحداث المشترك بها.
  • اختيار أنواع الأحداث للاشتراك بها — أحداث المصادقة، وأحداث التسليم، وأحداث الردود.
  • إرسال طلب اختبار (test ping) إلى نقطة الاستقبال الخاصة بك للتأكد من أنها قابلة للوصول وتستجيب بشكل صحيح قبل الاعتماد عليها في بيئة الإنتاج.
  • تدوير سر الويب هوك (webhook secret) إذا اشتبهت في تسريبه، دون الحاجة لإعادة تسجيل رابط نقطة الاستقبال.

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

فئة الحدثالوصف
Auth (المصادقة)أحداث متعلقة بتدفقات المصادقة/رمز التحقق OTP (مثل رموز التحقق المرسلة عبر Mersal).
Delivery (التسليم)تحديثات حالة تسليم الرسائل المرسلة (قيد الانتظار، تم التسليم، فشل، إلخ) عبر SMS وWhatsApp والبريد الإلكتروني.
Reply (الرد)الردود الواردة من المستلمين، مفيدة للمحادثات ثنائية الاتجاه ومحفزات الأتمتة.

استخدم إجراء طلب الاختبار (test ping) بعد تسجيل نقطة الاستقبال للتحقق من أن خادمك يُرجع استجابة ناجحة قبل الاعتماد على حركة البيانات الفعلية.

تحقق من سر الويب هوك

تحقق دائمًا من صحة طلبات الويب هوك الواردة باستخدام سر الويب هوك الخاص بك قبل الوثوق بالمحتوى. إذا قمت بتدوير السر، حدّثه على خادم الاستقبال لديك في نفس الوقت — التوقيعات القديمة لن تعود صالحة.

مثال: نقطة استقبال بسيطة

<?php
// webhook.php — نقطة استقبال أحداث مرسال
$payload = json_decode(file_get_contents('php://input'), true);
 
// تحقق من السر قبل الوثوق بالحمولة
$secret = getenv('MERSAL_WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';
if (!hash_equals($secret, $signature)) {
    http_response_code(401);
    exit;
}
 
switch ($payload['event'] ?? '') {
    case 'message.delivered':
        // حدّث حالة الرسالة في قاعدة بياناتك
        break;
    case 'message.failed':
        // سجّل الفشل أو أعد المحاولة عبر قناة أخرى
        break;
    case 'message.reply':
        // خزّن الرد أو مرّره لفريق خدمة العملاء
        break;
}
 
http_response_code(200); // مهم: رد بـ 200 حتى لا يعيد مرسال المحاولة
echo 'ok';

الأخطاء

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

هل ساعدتك هذه الصفحة؟
Webhooks · شروحات مرسال