
الطريقة البدائية لمعرفة هل وصلت رسالتك أن تسأل الخادم كل دقيقة: «وصلت؟ وصلت؟». هذا يستهلك الطلبات ويتأخر دائمًا. Webhooks في Mersal تعكس الاتجاه: مرسال يستدعي خادمك لحظة تسليم الرسالة أو فشلها أو وصول رد من العميل. لكن نقطة الاستقبال باب مفتوح على الإنترنت، فيجب أن ترفض الطلبات المزيفة، وتتحمل وصول الحدث نفسه مرتين، وترد بسرعة. نبني هنا نقطة استقبال تحقق الثلاثة.
مواصفات نقطة الاستقبال الجيدة
- HTTPS فقط، وتتحقق من السر في ترويسة الطلب بمقارنة ثابتة الزمن قبل قراءة أي شيء.
- تحفظ الحدث وترد 200 فورًا، وتعالجه لاحقًا؛ الرد البطيء أو الخطأ يجعل المرسل يعيد المحاولة.
- معالجة متكررة الأمان (idempotent): الحدث نفسه مرتين لا يغيّر النتيجة.
التسجيل والأحداث المتاحة
التسجيل يتم من لوحة مرسال لا عبر الـ API: من Automation ← Webhooks أضف رابط نقطة الاستقبال، واختر فئات الأحداث، وأرسل اختبار ping للتأكد أن خادمك يرد بنجاح. ومن الشاشة نفسها يمكن تدوير السر إذا شككت في تسربه دون إعادة تسجيل الرابط.
| الفئة | ماذا تحمل | استخدام شائع |
|---|---|---|
| Auth | أحداث التحقق ورموز OTP المرسلة عبر مرسال | تتبع نجاح التحقق في نظامك |
| Delivery | حالة التسليم: في الطابور، وسُلّمت، وفشلت، عبر SMS وواتساب والبريد | تحديث حالة الرسالة في الطلب، والتحويل لقناة أخرى عند الفشل |
| Reply | الردود الواردة من المستلمين | توجيه الرد لفريق الدعم، أو بدء أتمتة |
في أمثلة التوثيق تظهر الأحداث بأسماء مثل message.delivered وmessage.failed وmessage.reply في حقل event.
البناء خطوة بخطوة
- 1
أنشئ مسارًا عبر HTTPS
رابط مخصص مثل /hooks/mersal، لا يمر بكاش الصفحات ولا بصفحة دخول، ومستثنى من قواعد الجدار الناري التي تحجب الطلبات الآلية.
- 2
تحقق من السر أولًا
مرسال يرسل السر في ترويسة X-Webhook-Secret. قارنه بالقيمة المحفوظة في متغير بيئة باستخدام hash_equals، وارفض بـ 401 إذا لم يطابق. لأن السر يُرسل كما هو لا كتوقيع للمحتوى، فإن HTTPS شرط لا خيار.
- 3
احفظ ورد بسرعة
اكتب المحتوى الخام في جدول، ثم أعد 200. لا تستدعِ واجهات أخرى أو ترسل بريدًا قبل الرد.
- 4
عالج بلا تكرار
خزّن بصمة لكل حدث في عمود فريد، فإذا وصل الحدث نفسه مرة أخرى يرفضه القيد ولا يُعالج مرتين.
- 5
راقب الفشل
سجّل كل طلب مرفوض وسبب رفضه، وكل حدث فشلت معالجته، وراجعها يوميًا في البداية.
<?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
كيف أختبر نقطة الاستقبال قبل الحملات؟
ماذا أفعل إذا تسرب السر؟
هل يمكن تسجيل Webhook عبر الـ API؟
من السلسلة
المرجع
Webhooks في توثيق مرسال ورموز الحالة. آخر قراءة 18 أكتوبر 2026.
اربط حالات الرسائل بنظامك
أحداث التحقق والتسليم والردود تصل إلى خادمك لحظة حدوثها، مع اختبار ping وتدوير للسر من لوحة مرسال.
مرسال للمطورين