الويب هوك (Webhooks)

يرسل الويب هوك الأحداث إلى خادمك لحظة وقوعها، فلا تحتاج إلى الاستعلام المتكرر من الواجهة البرمجية. ترسل المنصة طلب POST موقّعًا إلى رابط تتحكم فيه عند وصول رسالة أو تغيّر حالة تسليم.

---

إنشاء نقطة استقبال

انتقل إلى الإعدادات ← المطورون وافتح قسم Webhooks.

أضف نقطة استقبال وحدد:

الحقل	الوصف
URL	رابط HTTPS خاص بك، ويجب أن يكون متاحًا للوصول العام
Events	الأحداث التي تريد استقبالها — انظر أدناه
Channel	تحديد قناة واحدة، أو تركها All channels
Connections	تقييد الاستقبال باتصالات محددة (اختياري)

سيتم توليد مفتاح توقيع (Signing Secret) خاص بك. انسخه — ستحتاجه للتحقق من الطلبات.

---

الأحداث

الحدث	متى يقع
message.received	عند وصول رسالة واردة على أي قناة مشترك بها
message.status	عند تغير حالة تسليم رسالة صادرة

ليست كل القنوات تبلّغ عن حالة التسليم:

القناة	message.received	message.status
واتساب — Baileys وBusiness وCloud API	نعم	نعم
فيسبوك ماسنجر	نعم	نعم
إنستجرام	نعم	نعم
تيليجرام	نعم	لا
ودجت المحادثة	نعم	لا
البريد الإلكتروني	نعم	لا

الاشتراك في message.status على نقطة استقبال خاصة بتيليجرام أو ودجت المحادثة أو البريد الإلكتروني مسموح، لكن تلك النقطة لن تستقبل أي حدث — فهذه القنوات لا تبلّغ عن حالة التسليم.

---

ترويسات الطلب

يحمل كل طلب ثلاث ترويسات:

الترويسة	معناها
X-RabtCRM-Signature	توقيع HMAC بصيغة sha256=<hex> لمحتوى الطلب الخام
X-RabtCRM-Event	اسم الحدث
X-RabtCRM-Delivery	معرّف ثابت للحدث، لا يتغير عبر إعادة المحاولات

---

محتوى الطلب

يستخدم كل طلب نفس الغلاف:

{
  "event": "message.received",
  "eventId": "evt_9f2c1a5b7d3e4f60",
  "teamId": 12,
  "channelType": "META-CLOUD",
  "sourceId": 99,
  "sourceName": "Main WhatsApp",
  "timestamp": "2026-08-29T10:15:04.221Z",
  "data": {
    "chatId": 32896,
    "remoteJid": "201025884633@s.whatsapp.net",
    "messageId": "wamid.HBgMMjAx...",
    "fromMe": false,
    "contactName": "Ahmed",
    "messageType": "conversation",
    "text": "مرحبًا، هل ما زال متوفرًا؟",
    "media": null,
    "timestamp": "2026-08-29T10:15:03.000Z"
  }
}

وعند إرفاق ملف يصبح الحقل media كائنًا بدلًا من null:

"media": {
  "url": "https://media.rabtcrm.com/...",
  "mimetype": "image/jpeg",
  "caption": "الأزرق"
}

أما حدث message.status فيحمل حقل data أصغر:

{
  "event": "message.status",
  "eventId": "evt_41b8c07e9a2d5f13",
  "teamId": 12,
  "channelType": "META-CLOUD",
  "sourceId": 99,
  "sourceName": "Main WhatsApp",
  "timestamp": "2026-08-29T10:15:09.882Z",
  "data": {
    "chatId": 32896,
    "remoteJid": "201025884633@s.whatsapp.net",
    "messageId": "wamid.HBgMMjAx...",
    "status": "delivered",
    "errorMessage": null
  }
}

---

التحقق من التوقيع

احسب HMAC-SHA256 لـ محتوى الطلب الخام باستخدام مفتاح التوقيع، ثم قارنه بترويسة X-RabtCRM-Signature.

مهم: احسب التوقيع على البايتات الخام كما وصلت. تحليل الـ JSON ثم إعادة تحويله إلى نص يغيّر البايتات ولن يتطابق التوقيع أبدًا.

import crypto from 'crypto';

function verify(rawBody, header, secret) {
  const expected =
    'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  // مقارنة بزمن ثابت — لا تستخدم === أبدًا
  const a = Buffer.from(expected);
  const b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or '')

---

الاستجابة

أرجع أي رمز حالة من نوع 2xx بأسرع ما يمكن. وأي رد آخر يُعد فشلًا ويؤدي إلى إعادة المحاولة.

نفّذ معالجتك الفعلية بعد إرسال الرد — فإذا استغرق معالجك أكثر من 10 ثوانٍ، تنتهي مهلة الطلب وتُعاد المحاولة رغم أنك استقبلته بالفعل.

---

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

تُعاد محاولة التسليم الفاشل 5 مرات بفواصل زمنية متزايدة:

المحاولة	الفاصل عن سابقتها
الأولى	دقيقة واحدة
الثانية	5 دقائق
الثالثة	30 دقيقة
الرابعة	ساعتان
الخامسة	6 ساعات

وبعد 6 محاولات إجمالًا يُسجَّل التسليم كفاشل ولا تُعاد المحاولة مرة أخرى.

---

تجاهل التكرار عبر معرّف التسليم

تبقى قيمة X-RabtCRM-Delivery (وكذلك eventId) ثابتة عبر كل إعادة محاولة لنفس الحدث. احفظ المعرّفات التي عالجتها وتجاهل المكرر منها — فقد يصلك الحدث نفسه أكثر من مرة، لأن التسليم مضمون "مرة واحدة على الأقل" وليس "مرة واحدة بالضبط".

---

القيود

لأسباب أمنية يجب أن يكون رابط الويب هوك متاحًا على الإنترنت العام. وتُرفض العناوين الداخلية والخاصة — مثل localhost والنطاقات الخاصة 10.x و192.168.x و172.16–31.x وعناوين link-local ونقاط بيانات الخدمات السحابية. كما لا يتم اتباع عمليات إعادة التوجيه.

---

الخطوة التالية

أرسل الرسائل برمجيًا من تطبيقك الخاص.

إرسال الرسائل ←