إنتقل إلى المحتوى الرئيسي

Webhooks

ما هو​

Webhooks هي نظام الإشعارات المدفوع بالأحداث في BotBat الذي يرسل تحديثات فورية إلى خادمك كلما حدث شيء مهم على المنصة. بدلاً من الاستعلام المتكرر عن API للتحقق من التغييرات، تقوم بتسجيل نقطة نهاية HTTPS، وتحديد أنواع الأحداث التي تهمك، ويرسل BotBat حمولات JSON مُنظمة إلى خادمك في اللحظة التي يحدث فيها الحدث. يتم توقيع كل حمولة بتوقيع HMAC-SHA256 حتى يتمكن خادمك من التحقق من أن الطلب صادر فعلاً من BotBat.

يتضمن نظام webhook سياسة إعادة محاولة قوية مع تراجع أسي. إذا كانت نقطة نهايتك غير متاحة مؤقتاً أو أرجعت رمز حالة غير 2xx، يعيد BotBat تلقائياً محاولة التسليم حتى خمس مرات خلال نافذة مدتها 12 ساعة. يتم تسجيل كل محاولة تسليم في لوحة تحكم BotBat مع نوع الحدث ورمز حالة HTTP من خادمك ووقت الاستجابة وعدد محاولات إعادة المحاولة، مما يمنحك رؤية كاملة لصحة التسليم.

تُعد Webhooks أساس التكاملات المدفوعة بالأحداث مع BotBat. تشغّل حالات استخدام تتراوح من مزامنة CRM الفورية ولوحات معلومات حالة التسليم إلى سجلات التدقيق للامتثال وسير عمل المتابعة الآلية. من خلال الاشتراك فقط في الأحداث التي يحتاجها تكاملك، تحافظ على الحد الأدنى من حمل المعالجة على خادمك مع الاستجابة الفورية للأحداث الأكثر أهمية.

متى تستخدمه​

السيناريوالوصف
مزامنة البيانات مع الأنظمة الخارجيةادفع تغييرات جهات الاتصال تلقائياً إلى نظام CRM أو مستودع البيانات أو أداة أتمتة التسويق عند إنشاء أو تحديث جهات اتصال في BotBat.
تفعيل سير عمل لاحقابدأ إجراءات متابعة في الخلفية عند اكتمال حملة أو حل محادثة. على سبيل المثال، تحديث حالة طلب أو إرسال استبيان رضا.
مراقبة تسليم الرسائل في الوقت الفعلياشترك في أحداث message.delivered وmessage.read لتحديث لوحات معلومات التسليم أو تفعيل متابعات حساسة زمنياً.
تدقيق الأحداث خارجياًأعد توجيه الأحداث إلى نظام تسجيل أو SIEM للامتثال والمراقبة الأمنية أو التحليلات المخصصة بما يتجاوز تقارير BotBat المدمجة.
تصحيح مشكلات التكاملاستخدم سجلات webhook وأدوات الاختبار للتحقق من أن الأحداث يتم إرسالها واستقبالها ومعالجتها بشكل صحيح أثناء التطوير.

الخطوات​

1. الانتقال إلى Webhooks​

اذهب إلى المطور > Webhooks في الشريط الجانبي. تعرض الواجهة الرئيسية جدولاً بجميع نقاط نهاية webhook المُهيأة، بما في ذلك اسم كل نقطة نهاية وعنوان URL وعدد الأحداث النشطة والحالة الحالية (نشط أو معطل).

Webhook endpoints list table showing endpoint name, URL, event count, and status

2. إنشاء نقطة نهاية webhook​

انقر على إضافة نقطة نهاية لفتح نموذج الإنشاء. أدخل عنوان HTTPS لخادمك (لا يُدعم HTTP العادي لأسباب أمنية)، وأعطِ نقطة النهاية اسماً وصفياً مثل "مزامنة جهات اتصال CRM" أو "متتبع حالة التسليم"، وحدد أنواع الأحداث التي يجب أن تفعّل الإشعارات لنقطة النهاية هذه. يمكنك تحديد أحداث فردية أو استخدام تحديد الكل لنقطة نهاية شاملة تستقبل كل نوع حدث.

Create endpoint form with URL input, name field, and event type checkboxes

تُقبل فقط نقاط نهاية HTTPS ذات شهادات SSL صالحة من سلطات شهادات موثوقة. سيتم رفض الشهادات الموقعة ذاتياً. إذا كنت تطور محلياً، استخدم أداة نفق مثل ngrok لعرض خادمك المحلي بعنوان HTTPS صالح.

3. نسخ مفتاح التوقيع​

بعد حفظ نقطة النهاية، ينشئ BotBat مفتاح توقيع فريداً. يُعرض هذا المفتاح مرة واحدة فقط. انسخه فوراً وخزّنه في مكان آمن مثل متغير بيئة أو مدير أسرار. ستستخدم هذا المفتاح على خادمك للتحقق من أصالة حمولات webhook الواردة.

Signing secret value shown with copy button after endpoint creation

4. تنفيذ التحقق من التوقيع​

على خادمك، احسب تجزئة HMAC-SHA256 لجسم الطلب الخام باستخدام مفتاح التوقيع كمفتاح. قارن الناتج السداسي عشري بالقيمة في ترويسة X-BotBat-Signature للطلب الوارد. إذا تطابقا، فالحمولة أصلية. إذا لم تتطابق، ارفض الطلب باستجابة HTTP 401. يلخص الجدول التالي خطوات التحقق من التوقيع.

الخطوةالإجراء
1اقرأ جسم الطلب الخام كسلسلة بايتات (لا تحلل JSON أولاً).
2استرجع قيمة ترويسة X-BotBat-Signature من الطلب.
3احسب HMAC-SHA256 للجسم الخام باستخدام مفتاح التوقيع الخاص بك كمفتاح.
4قارن الناتج السداسي عشري المحسوب بقيمة الترويسة باستخدام دالة مقارنة ذات وقت ثابت.
5إذا تطابقت القيم، عالج الحمولة. إذا لم تتطابق، أرجع HTTP 401 وتجاهل الطلب.

5. معالجة الحمولة​

حلّل جسم JSON. كل حمولة webhook تتبع بنية متسقة مع أربعة حقول رئيسية.

الحقلالنوعالوصف
eventstringمعرّف نوع الحدث، مثل message.delivered أو contact.created.
timestampstring (ISO 8601)الطابع الزمني بتوقيت UTC لوقت حدوث الحدث.
webhook_idstringمعرّف فريد لهذا التسليم المحدد. استخدمه للتحقق من عدم التكرار.
dataobjectالحمولة الخاصة بالحدث التي تحتوي على بيانات المورد ذات الصلة.

مثال على الحمولة:

{
  "event": "message.delivered",
  "timestamp": "2026-02-11T14:30:00.000Z",
  "webhook_id": "wh_evt_abc123def456",
  "data": {
    "message_id": "msg_789xyz",
    "contact_id": "ct_456abc",
    "channel": "whatsapp",
    "delivered_at": "2026-02-11T14:29:58.000Z"
  }
}

6. إرجاع استجابة 2xx​

يجب أن تُرجع نقطة نهايتك رمز حالة HTTP 2xx خلال 30 ثانية لتأكيد الاستلام. أي رمز حالة غير 2xx أو انتهاء مهلة تتجاوز 30 ثانية يفعّل سياسة إعادة المحاولة. أفضل ممارسة هي قبول webhook فوراً (إرجاع 200 بجسم فارغ أو {"ok": true})، ثم معالجة الحدث بشكل غير متزامن باستخدام طابور مهام أو عامل في الخلفية.

7. مراقبة سجلات webhook​

في لوحة تحكم BotBat، افتح تبويب السجلات لأي نقطة نهاية webhook. يتم تسجيل كل محاولة تسليم مع نوع الحدث ورمز حالة HTTP الذي أرجعه خادمك ووقت الاستجابة بالمللي ثانية وعدد محاولات إعادة المحاولة. يمكنك تصفية السجلات حسب نوع الحدث والحالة (نجاح، فشل، قيد إعادة المحاولة) ونطاق التاريخ.

Webhook delivery logs table showing event type, HTTP status, response time, and retry count

انقر على أي إدخال في السجل لتوسيعه وعرض حمولة الطلب الكاملة المرسلة وجسم الاستجابة الذي أرجعه خادمك وأي تفاصيل أخطاء. هذا لا يُقدّر بثمن لتصحيح أخطاء التسليمات الفاشلة.

Failed delivery detail showing request payload, response body, and error details

8. الاختبار محلياً​

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

Send Test Event modal with event type dropdown and Send button

أنواع الأحداث​

يسرد الجدول التالي جميع أنواع أحداث webhook المتاحة. اشترك فقط في الأحداث التي يحتاجها تكاملك لتقليل المعالجة غير الضرورية على خادمك.

الحدثالمُفعّلحالة الاستخدام النموذجية
message.receivedوصول رسالة واردة جديدة من جهة اتصال.توجيه الرسائل الواردة إلى نظام الدعم أو روبوت المحادثة.
message.sentإرسال رسالة صادرة إلى جهة اتصال.تسجيل النشاط الصادر في CRM.
message.deliveredتأكيد تسليم رسالة صادرة إلى جهاز جهة الاتصال.تحديث لوحات معلومات التسليم في الوقت الفعلي.
message.readقراءة جهة الاتصال للرسالة الصادرة.تفعيل متابعات حساسة زمنياً أو قياس التفاعل.
campaign.completedانتهاء الحملة من الإرسال لجميع المستلمين.إنشاء تحليلات ما بعد الحملة أو إخطار أصحاب المصلحة.
contact.createdإنشاء جهة اتصال جديدة في BotBat.مزامنة جهة الاتصال مع CRM أو مستودع البيانات.
contact.updatedتحديث حقول جهة اتصال موجودة.الحفاظ على مزامنة الأنظمة الخارجية مع أحدث بيانات جهات الاتصال.
conversation.assignedتعيين محادثة لوكيل.إشعار الوكيل عبر Slack أو البريد الإلكتروني أو أدواتك الداخلية.
conversation.resolvedوضع علامة "محلولة" على المحادثة.تفعيل استبيان رضا أو إغلاق تذكرة دعم.

سياسة إعادة المحاولة​

عندما تفشل نقطة نهايتك في إرجاع استجابة 2xx، يعيد BotBat المحاولة بتراجع أسي وفقاً للجدول التالي.

المحاولةالتأخير بعد الفشل السابق
إعادة المحاولة الأولىدقيقة واحدة
إعادة المحاولة الثانية5 دقائق
إعادة المحاولة الثالثة30 دقيقة
إعادة المحاولة الرابعةساعتان
إعادة المحاولة الخامسة12 ساعة

بعد 5 محاولات فاشلة متتالية، يتم وضع علامة "فاشل" بشكل دائم على الحدث في سجلات webhook. إذا فشلت نقطة نهاية باستمرار لمدة 72 ساعة عبر أحداث متعددة، يعطّل BotBat نقطة النهاية تلقائياً ويرسل إشعاراً بالبريد الإلكتروني لجميع مسؤولي مساحة العمل. يمكنك إعادة تفعيل نقطة نهاية معطلة من صفحة إعدادات Webhooks بعد حل المشكلة الأساسية.

الأخطاء الشائعة​

الخطأالتأثيرالتوصية
عدم التحقق من توقيعات webhookأي طرف يكتشف عنوان URL لنقطة نهايتك يمكنه إرسال أحداث مزيفة، مما قد يفسد بياناتك.تحقق دائماً من ترويسة X-BotBat-Signature باستخدام HMAC-SHA256 مع مفتاح التوقيع الخاص بك.
معالجة webhooks بشكل متزامنالعمليات البطيئة (كتابة قاعدة البيانات، استدعاءات API الخارجية) قبل إرجاع الاستجابة قد تسبب انتهاء المهلة وتفعّل محاولات إعادة غير ضرورية.أرجع استجابة 2xx فوراً، ثم عالج الحدث بشكل غير متزامن عبر طابور مهام.
عدم التعامل مع التسليمات المكررةقد تتسبب مشكلات الشبكة في تسليم نفس الحدث أكثر من مرة، مما يؤدي إلى سجلات مكررة أو إجراءات مُعالجة مرتين.استخدم حقل webhook_id لضمان عدم التكرار. تحقق مما إذا كنت قد عالجت معرّفاً معيناً بالفعل قبل التصرف بناءً عليه.
استخدام HTTP بدلاً من HTTPSيرفض BotBat نقاط النهاية غير المُشفرة بـ HTTPS. كما يتم رفض الشهادات الموقعة ذاتياً.استخدم شهادة SSL صالحة من سلطة شهادات موثوقة. للتطوير المحلي، استخدم أداة نفق.
الاشتراك في جميع الأحداث دون ضرورةاستقبال أحداث لا يستخدمها تكاملك يهدر عرض النطاق الترددي وموارد المعالجة على خادمك.اشترك فقط في أنواع الأحداث المحددة التي يتطلبها تكاملك.
تلميح

أثناء التطوير، استخدم زر "إرسال حدث اختباري" مع أداة نفق مثل ngrok لاختبار معالج webhook الخاص بك محلياً. يتيح لك ذلك التكرار بسرعة دون الحاجة للنشر إلى خادم بعد كل تغيير.

  • قائمة Webhooks
  • إنشاء Webhook
  • مفتاح التوقيع السري
  • أنواع الأحداث
  • سجلات Webhooks
  • إرسال حدث تجريبي
  • سياسة إعادة المحاولة
  • التحقق من التوقيع