تخطَّ إلى المحتوى

أهلاً بيك في ميرور

سجّل دخولك لمتابعة طلباتك واشتراكاتك ورصيد محفظتك.

هدية في محفظتك عند إنشاء حساب جديد

تسجيل الدخول إنشاء حساب جديد
تواصل عبر واتساب

شروحات ودلائل

Webhooks في Mersal: متابعة التسليم والردود بدل الاستعلام المتكرر

قراءة في 3 دقائق

Mersal Webhooks — MirrorORG

الطريقة البدائية لمعرفة هل وصلت رسالتك أن تسأل الخادم كل دقيقة: «وصلت؟ وصلت؟». هذا يستهلك الطلبات ويتأخر دائمًا. Webhooks في Mersal تعكس الاتجاه: مرسال يستدعي خادمك لحظة تسليم الرسالة أو فشلها أو وصول رد من العميل. لكن نقطة الاستقبال باب مفتوح على الإنترنت، فيجب أن ترفض الطلبات المزيفة، وتتحمل وصول الحدث نفسه مرتين، وترد بسرعة. نبني هنا نقطة استقبال تحقق الثلاثة.

مواصفات نقطة الاستقبال الجيدة

  • HTTPS فقط، وتتحقق من السر في ترويسة الطلب بمقارنة ثابتة الزمن قبل قراءة أي شيء.
  • تحفظ الحدث وترد 200 فورًا، وتعالجه لاحقًا؛ الرد البطيء أو الخطأ يجعل المرسل يعيد المحاولة.
  • معالجة متكررة الأمان (idempotent): الحدث نفسه مرتين لا يغيّر النتيجة.

التسجيل والأحداث المتاحة

التسجيل يتم من لوحة مرسال لا عبر الـ API: من Automation ← Webhooks أضف رابط نقطة الاستقبال، واختر فئات الأحداث، وأرسل اختبار ping للتأكد أن خادمك يرد بنجاح. ومن الشاشة نفسها يمكن تدوير السر إذا شككت في تسربه دون إعادة تسجيل الرابط.

الفئةماذا تحملاستخدام شائع
Authأحداث التحقق ورموز OTP المرسلة عبر مرسالتتبع نجاح التحقق في نظامك
Deliveryحالة التسليم: في الطابور، وسُلّمت، وفشلت، عبر SMS وواتساب والبريدتحديث حالة الرسالة في الطلب، والتحويل لقناة أخرى عند الفشل
Replyالردود الواردة من المستلمينتوجيه الرد لفريق الدعم، أو بدء أتمتة

في أمثلة التوثيق تظهر الأحداث بأسماء مثل message.delivered وmessage.failed وmessage.reply في حقل event.

البناء خطوة بخطوة

  1. 1

    أنشئ مسارًا عبر HTTPS

    رابط مخصص مثل /hooks/mersal، لا يمر بكاش الصفحات ولا بصفحة دخول، ومستثنى من قواعد الجدار الناري التي تحجب الطلبات الآلية.

  2. 2

    تحقق من السر أولًا

    مرسال يرسل السر في ترويسة X-Webhook-Secret. قارنه بالقيمة المحفوظة في متغير بيئة باستخدام hash_equals، وارفض بـ 401 إذا لم يطابق. لأن السر يُرسل كما هو لا كتوقيع للمحتوى، فإن HTTPS شرط لا خيار.

  3. 3

    احفظ ورد بسرعة

    اكتب المحتوى الخام في جدول، ثم أعد 200. لا تستدعِ واجهات أخرى أو ترسل بريدًا قبل الرد.

  4. 4

    عالج بلا تكرار

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

  5. 5

    راقب الفشل

    سجّل كل طلب مرفوض وسبب رفضه، وكل حدث فشلت معالجته، وراجعها يوميًا في البداية.

php
<?php
// hooks/mersal.php — استقبال أحداث مرسال وحفظها للمعالجة لاحقًا
$secret = (string) getenv( 'MERSAL_WEBHOOK_SECRET' );
$given  = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';
if ( '' === $secret || ! hash_equals( $secret, $given ) ) {
	http_response_code( 401 );
	exit;
}

$raw = file_get_contents( 'php://input' );
if ( null === json_decode( $raw, true ) ) {
	http_response_code( 400 );
	exit;
}

$pdo = new PDO( getenv( 'DB_DSN' ), getenv( 'DB_USER' ), getenv( 'DB_PASS' ) );
// الجدول: id, hash CHAR(64) UNIQUE, payload JSON, received_at, processed_at NULL
$stmt = $pdo->prepare( 'INSERT IGNORE INTO mersal_events (hash, payload, received_at) VALUES (?, ?, NOW())' );
$stmt->execute( array( hash( 'sha256', $raw ), $raw ) );

http_response_code( 200 ); // رد سريع حتى لا يعيد مرسال المحاولة
echo 'ok';

ثم تقرأ مهمة كرون كل دقيقة الأحداث التي لم تُعالج: تحدّث حالة الرسالة في الطلب عند message.delivered، وتجرّب قناة بديلة أو تنبّه الفريق عند message.failed، وتنشئ تذكرة دعم عند message.reply.

لا تفترض ترتيب الأحداثقد يصل حدث «سُلّمت» قبل أن تكتب قاعدتك أن الرسالة أُرسلت، خصوصًا مع الطوابير. اجعل المعالجة تقبل الحالة الأحدث فقط، ولا تعيد رسالة «سُلّمت» إلى «في الطابور».

Webhook أم استعلام دوري؟

المعيارWebhookالاستعلام عبر GET /api/get/{channel}
التأخيرلحظي تقريبًابقدر الفاصل بين الاستعلامات
عدد الطلباتطلب لكل حدث فقططلبات مستمرة حتى بلا جديد
الردود الواردةتصل كأحداثغير مناسب لها
متى تستخدمهالتشغيل اليوميالمراجعة والتسوية أو عند تعطل نقطة الاستقبال

أسئلة عن Webhooks

كيف أختبر نقطة الاستقبال قبل الحملات؟
استخدم اختبار ping من شاشة Webhooks في مرسال، وتأكد أن خادمك رد 200 وأن السجل حُفظ. ثم أرسل رسالة حقيقية لرقمك وراقب وصول حدث التسليم.
ماذا أفعل إذا تسرب السر؟
دوّره من الشاشة نفسها، وحدّث القيمة على خادمك في الوقت ذاته، لأن الطلبات بالسر القديم ستُرفض بعد التدوير.
هل يمكن تسجيل Webhook عبر الـ API؟
بحسب التوثيق، إدارة Webhooks تتم من لوحة التحكم، ولا توجد لها واجهة موثقة.

من السلسلة

المرجع

Webhooks في توثيق مرسال ورموز الحالة. آخر قراءة 18 أكتوبر 2026.

اربط حالات الرسائل بنظامك

أحداث التحقق والتسليم والردود تصل إلى خادمك لحظة حدوثها، مع اختبار ping وتدوير للسر من لوحة مرسال.

مرسال للمطورين

شارك المقال

اترك تعليقاً

لن يتم نشر عنوان بريدك الإلكتروني. الحقول الإلزامية مشار إليها بـ *