ما هو Webhook (الويبهوك) في واتساب API؟ شرح مبسط بالأمثلة

آخر تحديث: 5 نوفمبر 2026 · إعداد: فريق مظبوت (MazBot) · المصدر الأساسي: توثيق Meta لـ Webhooks في منصة واتساب للأعمال، وصفحة «Webhook» في لوحة مظبوت كما راجعناها في 5 نوفمبر 2026

الإجابة المختصرة: Webhook (الويبهوك) إشعار تلقائي ترسله خوادم Meta إلى رابط على خادمك فور وقوع حدث على رقمك: رسالة جديدة من عميل، أو تغيّر حالة رسالتك إلى «سُلّمت» أو «قُرئت» أو «فشلت»، أو تغيّر حالة قالب. يصلك طلب POST فيه JSON حتى 3 ميجابايت، وعلى خادمك أن يرد بـ 200، وإلا تعيد Meta المحاولة مدة تصل إلى 7 أيام.

هذه صفحة تعريف بالمصطلح. والمفهومان المرتبطان به: ما هو Cloud API في واتساب؟ وما هو Access Token (رمز الوصول)؟

محتوى المقال:

ما هو Webhook في واتساب API؟

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

تشبيه بسيط: الـ API أن تذهب أنت إلى مكتب البريد لترسل خطاباً، والويبهوك جرس الباب: ساعي البريد يأتيك عندما يصل شيء. لذلك يعمل الاثنان معاً: Cloud API لإرسال رسائلك، والويبهوك لاستقبال ردود العملاء ومعرفة مصير ما أرسلته.

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

كيف يعمل الويبهوك في واتساب خطوة بخطوة؟

  1. رابط استقبال (Callback URL): عنوان HTTPS بشهادة TLS صالحة؛ Meta لا تقبل الشهادات الموقّعة ذاتياً (self-signed).
  2. رمز تحقق (Verify Token): نص سري تختاره أنت وتحفظه على خادمك.
  3. طلب التحقق: ترسل Meta طلب GET فيه hub.mode=subscribe وhub.challenge وhub.verify_token. إن طابق الرمز ما عندك، يرد خادمك بـ 200 ومعه قيمة hub.challenge كما هي؛ وبغير ذلك لا تُرسل أي إشعارات.
  4. الاشتراك في الحقول: تختار من لوحة التطبيق (App Dashboard ← WhatsApp ← Configuration) أنواع الأحداث التي تريدها، ويجب أن يكون تطبيقك مشتركاً في حساب واتساب للأعمال (WABA).
  5. الإشعارات: كل حدث يصلك POST فيه JSON وترويسة توقيع X-Hub-Signature-256.
  6. الرد بـ 200: تعتبر Meta أي رد غير 200 فشلاً، فتعيد المحاولة فوراً ثم عدة مرات بتكرار يقل تدريجياً خلال 7 أيام، وبعدها يُسقط الإشعار.

ما أهم حقول الويبهوك (Webhook fields) في واتساب؟

«الحقل» هو نوع الأحداث الذي تشترك فيه. تذكر Meta 20 حقلاً، وهذه أكثرها استخداماً لأصحاب الأنشطة:

الحقلماذا يخبركمثال على الاستخدام
messagesرسائل العملاء الواردة، وحالة رسائلك الصادرةعرض الرسالة في صندوق الوارد، واكتشاف الرسائل الفاشلة
message_template_status_updateتغيّر حالة قالب موجودتنبيه الفريق لحظة اعتماد قالب الحملة أو رفضه
message_template_quality_updateتغيّر تقييم جودة القالبمراجعة نص الحملة قبل أن تتوقف
template_category_updateتغيّر فئة القالبمعرفة أن قالباً صار Marketing فتغيّر سعره
phone_number_quality_updateتغيّر مستوى سرعة الإرسال (throughput) للرقمضبط سرعة الحملات الكبيرة
account_alerts و account_updateتغييرات حد الرسائل وملف النشاط والتوثيق، وانتهاكات السياسةالتحرك سريعاً عند أي تقييد على الحساب
user_preferencesإيقاف العميل لرسائل التسويق أو استئنافهاإخراجه من قوائم العروض، كما في ما هو Opt-out؟
history و smb_message_echoes و smb_app_state_syncللأرقام المربوطة مع تطبيق واتساب بيزنس: سجل المحادثات، والرسائل المرسلة من التطبيق، ومزامنة جهات الاتصالالربط المزدوج (Coexistence)

حسب صفحة Webhooks overview من Meta، اطّلعنا عليها في 5 نوفمبر 2026.

كيف يبدو إشعار الرسالة من الداخل؟

كل إشعار في حقل messages له الهيكل نفسه: حساب واتساب للأعمال في entry.id، ثم changes وفيها اسم الحقل والقيمة. هذا مثال مبسط لرسالة نصية من عميل في القاهرة:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "...", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "Ahmed" }, "wa_id": "201001234567" }],
        "messages": [{ "from": "201001234567", "id": "wamid.xxx", "timestamp": "...",
                       "type": "text", "text": { "body": "عايز أعرف سعر الشحن" } }]
      }
    }]
  }]
}

وعند تغيّر حالة رسالة أرسلتها يأتي في المكان نفسه مصفوفة statuses بدلاً من messages، وفيها معرّف رسالتك والحالة ووقتها ورقم المستلم:

الحالةمعناها
sentخرجت الرسالة من Meta (علامة صح واحدة)
deliveredوصلت إلى جهاز العميل
readفتحها العميل
failedلم تُسلَّم، ومعها مصفوفة errors فيها كود الخطأ

كود الخطأ هو مفتاح الحل، مثل 131047 لانتهاء نافذة الـ 24 ساعة؛ ومعاني الأكواد كلها في أكواد أخطاء واتساب API ومعناها وحلها. وإن بقيت رسائلك عند الحالة sent طويلاً فاقرأ رسالة واتساب بعلامة صح واحدة ومش بتوصل.

كيف تحمي رابط الويبهوك وتتعامل مع التكرار؟

  • تحقق من التوقيع في كل طلب: احسب HMAC-SHA256 للنص الخام بـ «سر التطبيق» (App Secret) مفتاحاً، وقارن النتيجة بما بعد sha256= في ترويسة X-Hub-Signature-256، وارفض أي طلب لا يطابق.
  • HTTPS بشهادة صالحة: وتدعم Meta أيضاً TLS المتبادل (mTLS) لمزيد من الحماية.
  • لا تعتمد على قائمة عناوين IP: تقول Meta إنها تغيّر عناوينها دورياً، وتقترح mTLS بديلاً.
  • أزل التكرار: إعادة المحاولة قد توصل الإشعار نفسه مرتين، وMeta تطلب منك معالجة ذلك. استخدم معرّف الرسالة (wamid) مفتاحاً فريداً في قاعدة بياناتك.
  • رد بسرعة وعالج لاحقاً: ضع الإشعار في طابور (queue) وارجع 200 فوراً، ثم عالجه في الخلفية (اقتراحنا).
  • سر التطبيق غير رمز الوصول: الويبهوك يُوقَّع بـ App Secret، أما طلبات الإرسال فتحتاج Access Token. احمِ الاثنين بالدرجة نفسها.

ما هو تجاوز رابط الويبهوك (Webhook override)؟

للتطبيق رابط ويبهوك افتراضي، لكن Meta تسمح برابط بديل على مستوى حساب واتساب للأعمال (عبر subscribed_apps مع override_callback_uri وverify_token) أو على مستوى Phone Number ID. وتبحث بالترتيب: رابط الرقم، ثم الحساب، ثم التطبيق. ويشمل التحويل حقولاً مثل messages وhistory وsmb_message_echoes، أما إشعارات القوالب والحساب فتذهب دائماً إلى رابط التطبيق. بهذه الآلية تستقبل المنصات رسائل كل عميل على رابط خاص بحسابه.

الويبهوك في مظبوت: من Meta إلى لوحتك ومن لوحتك إلى نظامك

1) استقبال ويبهوك Meta: لا تحتاج خادماً

عندما تربط رقمك بزر «ربط واتساب» (التسجيل المدمج)، يضبط مظبوت رابط الاستقبال الخاص بحسابك ويشترك فيه تلقائياً بالحقل messages، ويضيف history وsmb_app_state_sync وsmb_message_echoes إذا ربطت رقمك مع بقاء تطبيق واتساب بيزنس، كما في الربط المزدوج (Coexistence). وإذا ظهر في «إعدادات واتساب» تنبيه بأن الويبهوك غير متصل، فزر «مزامنة» في بطاقة الحساب يعيد فحص رمز الوصول والاشتراك.

2) إرسال الأحداث إلى نظامك: Webhooks صادرة موقّعة

إن كان لديك نظام خاص (متجر، برنامج حجز، CRM) فمن «الإعدادات» ← «Webhook» في لوحة مظبوت:

  1. ضع رابط HTTPS يقبل طلبات POST.
  2. اختر «الأحداث المشتركة»؛ وترك الكل محدداً يعني استقبال كل الأحداث.
  3. احفظ، فيُنشأ «مفتاح توقيع Webhook» تلقائياً. وإن تسرّب فعّل «إعادة إنشاء مفتاح التوقيع عند الحفظ».
  4. تحقق من كل طلب بالترويسة X-Mazbot-Signature، وقيمتها sha256= متبوعة بـ HMAC-SHA256 للنص الخام بمفتاحك.
الحدثمتى يصلك
message.receivedالعميل أرسل نصاً أو وسائط، ومعه رقمه واسمه ونص الرسالة
interactive.selectedضغط زراً أو اختار من قائمة، ومعه معرّف الاختيار في data.selection.id
appointment.created / updated / cancelledحجز أُنشئ أو عُدّل موعده أو أُلغي عبر API
custom. وأحداث التسجيل وكلمة المرورأحداث تطلقها من نظامك عبر POST /webhooks/emit فتصل إلى الرابط نفسه

حسب صفحة «Webhook» في لوحة مظبوت ودليل التكامل، كما راجعناهما في 5 نوفمبر 2026.

ويحمل كل طلب ترويستي X-Mazbot-Event-Type وX-Mazbot-Delivery-Id، والثانية تساوي معرّف الحدث فتستخدمها لإزالة التكرار. وإذا لم يستجب رابطك أو رد برمز مثل 429 أو 5xx، يحاول مظبوت التسليم حتى 5 مرات بفواصل من 15 ثانية إلى 10 دقائق. وعند تكرار الفشل تعرض الصفحة آخر خطأ، ثم يتوقف الإرسال مؤقتاً حتى تصلح الرابط وتضغط «حفظ».

مثالان على الويبهوك من القاهرة والرياض

عيادة أسنان في الرياض: يراسلها المريض لحجز موعد، فيرسل نظام الحجز عبر API مظبوت رسالة تفاعلية بثلاثة أزرار معرّفاتها confirm_reservation وreschedule_reservation وcancel_reservation. يضغط المريض «تأكيد»، فيصل إلى نظام العيادة حدث interactive.selected بالمعرّف confirm_reservation، فيعلّم الموعد مؤكداً دون أن يلمسه موظف. ولأن النظام يقرأ المعرّف لا نص الزر، يبقى الربط سليماً لو تغيّر النص.

متجر إلكترونيات في مدينة نصر: يشترك في message.received فقط. كل رسالة تصل من رقم عليه طلب مفتوح في نظام المتجر تُسجَّل في ملف الطلب نفسه، فيرى موظف الشحن أن العميل كتب «غيّروا العنوان للتجمع الخامس» قبل خروج الطلب. وإذا تعطل خادم المتجر ليلاً، يعيد مظبوت المحاولة، ويستخدم المتجر X-Mazbot-Delivery-Id حتى لا تُسجَّل الرسالة مرتين.

والاتجاه العكسي: نظامك يرسل قالباً عبر API، والويبهوك يعيد إليك رد العميل، كما في تأكيد طلبات الدفع عند الاستلام على واتساب وتذكير مواعيد العيادات تلقائياً.

كيف يساعدك مظبوت؟

  • يستقبل ويبهوك Meta عنك: رسائل عملائك وحالات رسائلك تظهر مباشرة في صندوق الوارد الموحد دون خادم أو برمجة.
  • Webhooks صادرة موقّعة بـ HMAC لنظامك، مع اختيار الأحداث، وإعادة المحاولة، وتنبيه عند تعطل رابطك.
  • API لإرسال القوالب والرسائل التفاعلية من متجرك أو برنامج الحجز.
  • ربط رسمي عبر Meta لرقمك الحالي مع بقاء تطبيق واتساب بيزنس، والربط الرسمي يقلل مخاطر الحظر اللي بتسببها الأدوات غير الرسمية، مع الالتزام بسياسات واتساب.
  • بدون أي عمولة على رسائل Meta، والاشتراك من 6$ شهرياً بعد خصم 50% (السعر الأصلي 12$).

أسئلة شائعة

ما الفرق بين Webhook وAPI في واتساب؟

الـ API طلب يرسله نظامك إلى Meta، مثل «أرسل هذا القالب». والويبهوك طلب ترسله Meta إلى نظامك، مثل «وصلت رسالة» أو «قُرئت رسالتك». تحتاج الاثنين: الأول للإرسال والثاني للاستقبال.

هل أحتاج ويبهوك خاصاً إذا كنت أستخدم منصة مثل مظبوت؟

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

ماذا يحدث إذا توقف خادمي يوماً كاملاً؟

تعيد Meta المحاولة بتكرار يقل تدريجياً حتى 7 أيام، فتصلك الإشعارات بعد عودة الخادم. وما يتجاوز 7 أيام يُسقط، ولا توجد واجهة لاسترجاعه.

هل يُحاسب إشعار الويبهوك كرسالة؟

لا. الإشعار ليس رسالة إلى عميل، وMeta تحاسب على الرسائل المُسلَّمة حسب فئتها ودولة العميل، كما في أسعار واتساب بيزنس API 2026.

المصادر

رسائل عملائك في لوحة واحدة.. وأحداثها في نظامك

مع مظبوت: ربط رسمي عبر Meta يستقبل ويبهوك رقمك عنك، وصندوق وارد لفريقك، وWebhooks صادرة موقّعة لنظامك، وAPI لإرسال القوالب، بدون أي عمولة على أسعار Meta. جرّب أول شهر مجاناً.. وبعده الباقات بخصم 50%، مع 250,000 توكن ذكاء اصطناعي مجاناً للحسابات الجديدة.

ابدأ تجربتك المجانية