Webhooks واتساب — الدليل الكامل للمطورين (2026)
Webhooks هي قلب أي منتج واتساب جاد. بدونها ستعود إلى Polling البطيء أو تفقد أحداثاً حرجة. هذا الدليل يشرح كيف تبني طبقة استقبال موثوقة مع Omdaa API.
لماذا Webhook أفضل من Polling؟
Polling يسأل السيرفر باستمرار: «هل هناك جديد؟». هذا يهدر موارد ويتأخر. Webhook يدفع الحدث لحظة حدوثه إلى endpointك. النتيجة: زمن استجابة أقل وتكلفة تشغيل أوضح.
أهم الأحداث التي ستتعامل معها
messages.upsert— رسالة واردة أو تحديث رسالة.connection.update— تغيّر حالة اتصال الجلسة.- أحداث الحالة (تسليم/قراءة) حسب ما يدعمه المسار.
ابدأ بدعم الرسائل النصية أولاً، ثم أضف الوسائط والأزرار لاحقاً.
شكل endpoint صحي
- يستقبل POST JSON.
- يتحقق من السر/التوقيع إن وُجد.
- يرد 200 خلال وقت قصير.
- يدفع المهمة إلى Queue/Worker.
- يعالج المنطق (بوت، AI، CRM) خارج مسار الطلب.
Idempotency: لا تعالج الحدث مرتين
قد يُعاد إرسال Webhook عند فشل أو timeout. خزّن messageId (أو بصمة الحدث) في Redis/Mongo مع TTL. قبل المعالجة تحقق: إن وُجد المعرف سابقاً، تجاهل بهدوء.
تدفق معالجة مقترح
- حفظ الحمولة الخام (raw) للتشخيص.
- تصنيف نوع الرسالة.
- إن نص: تشغيل قواعد/AI.
- إرسال رد عبر Omdaa API.
- تحديث حالة المحادثة في DB.
- تسجيل مقاييس النجاح/الفشل.
التعامل مع انقطاع الجلسة
عند connection.update بحالة منقطعة، أرسل تنبيهاً داخلياً للفريق. لا تترك العملاء يرسلون إلى فراغ. بعض الانقطاعات مؤقتة (مثل 503) وتعود تلقائياً — راقب المدة لا الحدث الواحد فقط.
الاختبار المحلي باحتراف
استخدم ngrok أو Cloudflare Tunnel. سجّل URL في لوحة Webhooks. أرسل رسالة حقيقية من هاتفك. اطبع الـ payload كاملاً مرة واحدة ثم ابنِ Parser ثابتاً. لا تفترض أسماء حقول من الذاكرة.
الأمان
- HTTPS إلزامي.
- سر مشترك أو تحقق توقيع.
- حد معدل الطلبات على الـ endpoint.
- لا تسجّل بيانات حساسة بالكامل في اللوج العام.
- افصل مفاتيح staging عن production.
إعادة المحاولة والطوابير
إذا فشل إرسال الرد بسبب شبكة، أعد المحاولة بأس وإقصاء (backoff). إن فشلت جلسة، لا تعِد المحاولة بلا نهاية — صفّر المهمة بعد تنبيه بشري.
مراقبة الإنتاج
- عدد الأحداث الواردة/ساعة.
- نسبة 4xx/5xx على endpoint.
- زمن المعالجة p50/p95.
- تنبيه عند صمت القناة فجأة.
- تنبيه عند ارتفاع فشل الإرسال.
أخطاء شائعة
- منطق ثقيل داخل الطلب مباشرة.
- نسيان Idempotency.
- Webhook على HTTP.
- خلط بيئات متعددة على نفس الرابط.
- عدم معالجة الوسائط بشكل صريح (تجاهل أو رسالة اعتذار).
خطة تنفيذ على أسبوع
- يوم 1: استقبال وطباعة payload.
- يوم 2: رد ثابت.
- يوم 3: Queue.
- يوم 4: Idempotency.
- يوم 5: تنبيهات الانقطاع.
- يوم 6–7: لوحة مقاييس بسيطة.
الخلاصة
Webhook ناجح = استجابة سريعة + معالجة غير متزامنة + تتبع + أمان. Omdaa يسهّل الإرسال والاستقبال حتى تركز على منطق عملك لا على بنية الرسائل.
نموذج بيانات مقترح للأحداث
احفظ على الأقل: معرف الحدث، معرف الرسالة، الجلسة، الرقم، نوع الرسالة، وقت الاستلام، حالة المعالجة، وعدد المحاولات. هذا الجدول يصبح أساس التقارير وتنظيف التكرار.
أضف حقلاً للخطأ الأخير حتى يستطيع الدعم معرفة سبب توقف رد معيّن دون قراءة ملفات لوج ضخمة.
اختبارات عقد Webhook
جهّز مجموعة fixtures لحمولات نموذجية: نص، صورة، رسالة فارغة، وانقطاع اتصال. شغّل اختباراً تلقائياً بعد كل تعديل على الـ parser. تغيير بسيط في اسم حقل قد يكسر الإنتاج بصمت.
وثّق نسخة الحمولة التي تعتمدها اليوم، وراجعها بعد تحديثات Omdaa أو تغيير مزود الاستضافة.
أداء تحت الضغط
حاكِ عشرات الأحداث المتتابعة في بيئة staging. راقب زمن الرد HTTP وطول الطابور. إن تجاوزت المعالجة قدرة السيرفر، زِد العمال قبل توسيع الحملات التسويقية.
الخطوة التالية: أنشئ حساباً مجاناً من omdaa.com/register، اربط جلسة واتساب، وابدأ التجربة خلال دقائق. Omdaa API مجاني للمنصة — بدون اشتراك شهري.
ملحق تطبيقي سريع
راجع إعدادات الجلسة أسبوعياً، وثّق المفاتيح دون تسريبها، واختبر مسار الرسالة الكاملة بعد أي تغيير في الـ Webhook أو الاستضافة. الانضباط التشغيلي أهم من إضافة ميزات جديدة بلا مراقبة.
شارك هذا الدليل مع فريقك، وحدّد مسؤولاً واحداً عن حالة الاتصال ومسؤولاً عن محتوى الردود. بهذا يقل التداخل وتزيد جودة خدمة واتساب مع نمو الاستخدام.
للمحافظة على استقرار الخدمة راقب الجلسات يومياً، راجع سجلات الإرسال بعد أي نشر، وحدّث نصوص الرد عند تغيّر الأسعار أو السياسات. الانضباط الصغير المتكرر أفضل من إصلاحات كبيرة متأخرة، وهو ما يفرق بين تجربة هواة وتشغيل احترافي على واتساب عبر Omdaa API في بيئة حقيقية مع عملاء فعليين وتوقعات واضحة للجودة.
للمحافظة على استقرار الخدمة راقب الجلسات يومياً، راجع سجلات الإرسال بعد أي نشر، وحدّث نصوص الرد عند تغيّر الأسعار أو السياسات. الانضباط الصغير المتكرر أفضل من إصلاحات كبيرة متأخرة، وهو ما يفرق بين تجربة هواة وتشغيل احترافي على واتساب عبر Omdaa API في بيئة حقيقية مع عملاء فعليين وتوقعات واضحة للجودة.
للمحافظة على استقرار الخدمة راقب الجلسات يومياً، راجع سجلات الإرسال بعد أي نشر، وحدّث نصوص الرد عند تغيّر الأسعار أو السياسات. الانضباط الصغير المتكرر أفضل من إصلاحات كبيرة متأخرة، وهو ما يفرق بين تجربة هواة وتشغيل احترافي على واتساب عبر Omdaa API في بيئة حقيقية مع عملاء فعليين وتوقعات واضحة للجودة.
للمحافظة على استقرار الخدمة راقب الجلسات يومياً، راجع سجلات الإرسال بعد أي نشر، وحدّث نصوص الرد عند تغيّر الأسعار أو السياسات. الانضباط الصغير المتكرر أفضل من إصلاحات كبيرة متأخرة، وهو ما يفرق بين تجربة هواة وتشغيل احترافي على واتساب عبر Omdaa API في بيئة حقيقية مع عملاء فعليين وتوقعات واضحة للجودة.