تدفق الأحداث: الويب هوك (Webhooks)

الويب هوك هي الجهاز العصبي لعملية التكامل مع واتساب. فهي تسمح لـ Wawp بدفع الأحداث في الوقت الفعلي (الرسائل، التفاعلات، تحديثات الحالة، إلخ) إلى خادمك فور وقوعها، مما يلغي الحاجة إلى الاستعلام المستمر (Polling) ويوفر استهلاك الموارد.

🏗️ ما هو الويب هوك؟

الويب هوك هو طلب HTTP POST يتم إرساله من Wawp إلى خادمك عند وقوع حدث ما على شبكة واتساب.

• قائم على الدفع (Push-Based): المتصفح أو الخادم الخاص بك لا يسأل عن التحديثات؛ بل يرسلها نظامنا تلقائيًا.
• وقت حقيقي (Real-Time): تصل الأحداث في غضون أجزاء مئوية من الثانية.
• انتقائي: يمكنك اختيار أنواع الأحداث التي ترغب في استلامها فقط لتقليل حركة مرور البيانات.

🚀 دليل الإعداد السريع

1. إنشاء نقطة نهاية (Endpoint)

يجب أن يكشف خادمك عن عنوان URL متاح للعامة يقبل طلبات POST. تأكد دائماً من الرد بـ 200 OK فوراً، مع معالجة الحدث برمجياً في الخلفية لتجنب تكرار الإرسال بسبب التأخير.

2. التكوين والاختبار

يمكنك تكوين الرابط واختيار الأحداث من لوحة التحكم. للاختبار المحلي، نوصي باستخدام أدوات مثل ngrok أو Hookdeck لفتح نفق (Tunnel) إلى جهاز المطور الخاص بك.

📦 هيكل الحدث (JSON Schema)

تتبع جميع الأحداث هذا الهيكل الموحد لسهولة المعالجة:

{
  "id": "evt_1234567890",
  "timestamp": 1722170400000,
  "session": "your_instance_id",
  "event": "message",
  "payload": { ... },
  "me": { "id": "your_number@c.us", "pushName": "Bot" }
}

🆔 مرجع معرفات واتساب (JID)

في Wawp، يتم تحديد كل كيان (جهة اتصال، مجموعة، قناة) بواسطة سلسلة فريدة تسمى JID. فهم هذه اللواحق ضروري لتوجيه الرسائل والأحداث بشكل صحيح:

🛡️ الأمن والموثوقية

1. التحقق من المصدر: نوصي بإضافة "معرف سري" (Secret Token) كباراميتر في رابط الويب هوك الخاص بك (مثل ?key=mysecret) والتحقق منه في خادمك لضمان أن الطلب قادم من Wawp.
2. إدارة التكرار (Idempotency): بما أن الشبكات الموزعة قد تعيد إرسال الحدث (عند تأخر الرد)، يجب على نظامك استخدام event.id للتأكد من عدم معالجة نفس الحدث مرتين في الـ CRM الخاص بك.
3. المعالجة غير المتزامنة: لا تجعل خادم الويب هوك ينتظر تنفيذ منطق العمل المعقد (مثل الاتصال بذكاء اصطناعي). ضع الحدث في "طابور" (Queue) وأرسل الرد لـ Wawp فوراً.

🎯 الخاتمة: الميزة التفاعلية

منظومة الويب هوك هي الجسر بين التطبيق الثاكن ومنصة المحادثة "الحية". من خلال الهندسة القائمة على رد الفعل (Reactive Design)، ستنتقل مؤسستك من مجرد "طلب البيانات" إلى الاستجابة المؤتمتة، متبعةً نبض شبكة واتساب العالمية بكل دقة واحترافية.