Webhook واتساب: استقبال أحداث واتساب وإنستغرام وماسنجر

webhook واتساب في مُجيب رابطٌ على خادمك يتلقى طلب POST موقّعًا كلما وقع حدث في نشاطك: عميل جديد، أو حجز جديد أو ملغى، أو تحويل محادثة إلى موظف، أو رسالة جديدة من واتساب أو إنستغرام أو ماسنجر. تنشئه من صفحة «التكاملات»، ويعيد مُجيب المحاولة وحده إذا فشل الإرسال.

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

ما الأحداث التي يرسلها webhook واتساب في مُجيب؟

يرسل مُجيب 5 أحداث، وتختار منها ما يحتاجه كل Webhook. كل حدث يصل طلبًا مستقلًا فيه JSON.

الحدث في اللوحة	الرمز	متى يُرسل
«عميل جديد»	`contact.created`	عند أول رسالة من مُرسِل جديد على إحدى القنوات، أو عندما تراسل من هاتف نشاطك رقمًا ليس عميلًا بعد، أو عندما يضيف أحد الفريق عميلًا من اللوحة
«حجز جديد»	`booking.created`	عندما يحجز الوكيل موعدًا أو يضيفه أحد الفريق في التقويم
«انلغى حجز»	`booking.cancelled`	عندما يُلغى موعد، من الوكيل أو من التقويم
«تحويل لموظف»	`conversation.handoff`	عندما يحوّل الوكيل محادثة إلى موظف
«رسالة جديدة»	`message.received`	مع كل رسالة يرسلها عميل، على أي قناة

أحداث الحجز تظهر في القائمة فقط إذا كان نشاطك يستخدم الحجوزات.
ردود الوكيل وردود الفريق لا تُرسل؛ حدث الرسالة للرسائل الواردة من العملاء وحدها.
الحقول الكاملة لكل حدث في مرجع أحداث webhook.

كيف أنشئ Webhook من لوحة مُجيب؟

تنشئه من قسم «للمطوّرين» في صفحة التكاملات، وتحتاج إلى حساب المالك أو حساب مدير.

افتح «التكاملات»، ثم افتح القسم «للمطوّرين».
اضغط «Webhook جديد».
اكتب في خانة «الاسم» اسمًا يذكّرك بالنظام الذي يستقبله، مثل «نظام مركز النخبة».
الصق في خانة «الرابط» رابط الاستقبال، مثل https://example.com/hooks/mujib.
اختر من «الأحداث» حدثًا واحدًا على الأقل، ثم اضغط «اعمل الـ Webhook».
تظهر رسالة «سر التوقيع — بيبين هالمرة بس» ومعها سر يبدأ بـ whsec_. اضغط «انسخ السر» واحفظه في إعدادات نظامك، فلن يظهر مرة أخرى.
اضغط «أرسل تجربة» ليصل إلى رابطك حدث تجربة من نوع webhook.test، ثم اضغط «خلصت».

نافذة Webhook جديد فيها الاسم والرابط والأحداث المختارة — عُبّئت خانتا «الاسم» و«الرابط» بعنوان مثال، وعُلِّمت ثلاثة أحداث تحت «الأحداث» يظهر بجانب كل منها اسمه البرمجي، قبل الضغط على «اعمل الـ Webhook».

يمكنك إنشاء 10 Webhooks على الأكثر لكل نشاط، ولكل واحد سره الخاص. ولتغيير الأحداث لاحقًا افتح الـ Webhook واضغط «غيّر» بجانب الأحداث.

ما الشروط التي يجب أن يستوفيها رابط الاستقبال؟

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

HTTPS فقط: الرابط الذي يبدأ بـ http:// يُرفض.
عنوان عام: يجب أن يشير اسم النطاق إلى عناوين عامة على الإنترنت؛ أما localhost والشبكات الداخلية والخاصة فتُرفض برسالة «هالرابط بيأشّر على عنوان داخلي أو خاص — لازم يكون عنوان عام على الإنترنت.».
اسم موجود: إذا لم يُعثر على النطاق تظهر رسالة «ما لقينا هالعنوان على الإنترنت — تأكد من الاسم.».
بلا بيانات دخول: لا تضع اسم مستخدم أو كلمة مرور داخل الرابط؛ تحقق من الطلب بالتوقيع بدلًا من ذلك.
المنفذ: المنفذ الافتراضي 443، أو أي منفذ من 1024 فما فوق.
العنوان النهائي: لا يتبع مُجيب إعادة التوجيه، فالرد من فئة 3xx يُعدّ فشلًا. ضع العنوان الذي يستقبل الطلب مباشرة.

كيف يبدو الطلب الذي يصل إلى رابطك؟

يصل كل حدث طلبَ POST جسمه JSON، ومعه هذه الترويسات:

الترويسة	قيمتها
`Content-Type`	`application/json`
`User-Agent`	`Mujib-Webhooks/1.0`
`X-Mujib-Event`	نوع الحدث، مثل `booking.created`
`X-Mujib-Delivery`	معرّف هذا الإرسال، ويبقى نفسه في كل إعادة محاولة
`X-Mujib-Signature`	التوقيع بصيغة `t=…,v1=…`، وشرحه في التحقق من توقيع webhook

ولكل حدث الغلاف نفسه: id معرّف الحدث، وtype نوعه، وcreatedAt وقت وقوعه بتوقيت UTC، وworkspaceId معرّف نشاطك، وdata تفاصيله. هذا مثال لحدث عميل جديد، منسّق هنا للقراءة؛ أما الجسم الفعلي فيصل في سطر واحد بلا مسافات:

{
  "id": "5d7c1e2a-3b4f-4c6d-9e8f-0a1b2c3d4e5f",
  "type": "contact.created",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "contact": {
      "id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "name": "سارة",
      "phone": "962790000000",
      "channel": "whatsapp",
      "stage": "new",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

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

بماذا يجب أن يرد خادمك؟

يكفي أن يرد خادمك بأي رمز من فئة 2xx خلال 10 ثوانٍ من بدء الطلب؛ وأي رد آخر يُعدّ فشلًا.

يجب أن يكتمل الاتصال الآمن بخادمك خلال 3 ثوانٍ، وإلا ظهر في السجل «ما قدرنا نفتح اتصال آمن مع رابطك خلال 3 ثواني».
ردود فئات 3xx و4xx و5xx كلها فشل يعيد مُجيب المحاولة بعده، وكذلك انقطاع الاتصال أو انتهاء المهلة.
مُجيب لا يستخدم جسم ردك ولا يحفظه، فيكفي رد فارغ.
تحقق من التوقيع واحفظ الحدث ثم رد فورًا، وأكمل المعالجة الطويلة بعد الرد حتى لا يتجاوز ردك المهلة.

ماذا يحدث إذا فشل الإرسال؟

يعيد مُجيب المحاولة وحده حتى 6 محاولات بالمجموع: ينتظر قبل الأولى 30 ثانية، ثم يتضاعف الانتظار كل مرة، فتكون المحاولة الأخيرة بعد نحو 15 دقيقة من الأولى.

كل إعادة محاولة تحمل الجسم نفسه والمعرّف X-Mujib-Delivery نفسه، بتوقيع جديد ووقت جديد.
قد يصلك الإرسال نفسه مرتين، مثلًا إذا عالجه خادمك وتأخر رده. احفظ قيمة X-Mujib-Delivery وتجاهل ما عالجته من قبل.
لا يضمن مُجيب ترتيب وصول الأحداث؛ اعتمد على createdAt إذا كان الترتيب مهمًا.
الرابط المرفوض أصلًا، كالعنوان الداخلي، لا يُعاد إليه الإرسال.
إذا نفدت المحاولات صار الإرسال «ما وصل» في السجل، ويمكنك إعادته يدويًا.

كيف أقرأ سجل الإرسال وأعيد إرسال ما فشل؟

افتح الـ Webhook من القائمة لترى «آخر الإرسالات»: آخر 20 إرسالًا، لكل منها حالته ورمز الرد ومدته وسبب الفشل إن فشل.

الحالة	معناها
«وصل»	رد خادمك برمز من فئة `2xx`
«عم ينبعث…»	الإرسال جارٍ أو ينتظر إعادة المحاولة
«ما وصل»	نفدت المحاولات، ويظهر تحته السبب وزر «أعد المحاولة»

«أعد المحاولة» يرسل الجسم نفسه بتوقيع جديد، حتى 3 محاولات.
«أرسل تجربة» يرسل حدث تجربة بمحاولة واحدة بلا إعادة، ويعمل حتى والـ Webhook موقوف.
مجموع ضغطات التجربة وإعادة الإرسال 30 مرة في الساعة لكل نشاط.
يحتفظ مُجيب بآخر 100 إرسال لكل Webhook.

لماذا توقّف الـ Webhook وحده، وكيف أعيد تشغيله؟

يوقف مُجيب الـ Webhook تلقائيًا بعد 20 إرسالًا فاشلًا متتاليًا، حتى لا يبقى يرسل إلى رابط لا يعمل. يظهر في صفحته تنبيه «وقّفناه لحاله بعد 20 إرسال فشلوا ورا بعض».

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

ما الفرق بين الإيقاف المؤقت وتجديد السر والحذف؟

كلها في صفحة الـ Webhook، وتختلف فيما يبقى بعدها.

الإجراء	ما يحدث
«موقّف مؤقتًا»	تتوقف الأحداث الجديدة، وتعيد التشغيل متى شئت. ما يقع في أثناء ذلك لا يُرسل
«جدّد السر»	يظهر سر جديد مرة واحدة، ويتوقف القديم فورًا؛ فحدّث نظامك مباشرة وإلا فشل التحقق من التوقيع
«احذف الـ Webhook»	يتوقف الإرسال نهائيًا ويبطل السر، وما وصل إلى نظامك يبقى عندك

إذا ضاع السر فلا سبيل إلى عرضه مرة أخرى: اضغط «جدّد السر» واحفظ السر الجديد.

الأسئلة الشائعة

هل يصل الـ Webhook برسائل إنستغرام وماسنجر أيضًا؟

نعم. أحداث العملاء والرسائل والتحويل تأتي من القنوات الثلاث، ويبيّن حقل channel القناة، وقيمته whatsapp أو instagram أو facebook لماسنجر.

هل يمكن أن يصل الحدث نفسه مرتين؟

نعم، إذا تأخر رد خادمك فأعاد مُجيب المحاولة. اعتمد على الترويسة X-Mujib-Delivery لتتجاهل ما عالجته من قبل.

هل تصلني لاحقًا الأحداث التي وقعت والـ Webhook موقوف؟

لا. ما يقع أثناء الإيقاف لا يُرسل بعد إعادة التشغيل، سواء أوقفته أنت أو توقف وحده بعد الفشل المتكرر.

كم Webhook أستطيع إنشاءه؟

حتى 10 لكل نشاط، ولكل واحد منها رابطه وسره وأحداثه.

هل يرسل مُجيب الصور والملفات الصوتية في الحدث؟

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

من يستطيع إنشاء Webhook؟

مالك الحساب والمديرون فقط، فصفحة التكاملات لا تظهر لبقية الفريق.

مُجيب منتج شركة المجيب الذكي لتكنولوجيا المعلومات (ذات مسؤولية محدودة)، عمّان، الأردن. رقم التسجيل82888.

الخصوصية الشروط تواصل معنا llms.txt