تكوين Webhooks

قم بإعداد webhooks لتلقي إشعارات في الوقت الفعلي للرسائل وتحديثات حالة التسليم وأحداث الحملات.

يرسل SendSeven HTTP POST إلى عنوان URL الخاص بك

إذا لم يكن هناك 200، نعيد المحاولة مع تأخير أسي

يظهر مصفوفة attachments فقط عندما تتضمن الرسالة وسائط. يتضمن كل مرفق معرّف id فريداً وcontent_type وfile_size وعنواني URL للتنزيل. الأنواع المدعومة: صورة، فيديو، صوت، مستند، ملصق.

url — نقطة اتصال API ثابتة. تتطلب مصادقة (مفتاح API أو رمز جلسة). لا تنتهي صلاحيتها أبداً.

signed_url — عنوان GCS موقّع مسبقاً. لا يتطلب مصادقة. تنتهي صلاحيته بعد 24 ساعة.

إذا فشل تنزيل الوسائط من المنصة، يتم تمرير البيانات الخام للمنصة مع علامة "source": "platform" بدلاً من الحقول المُثرَاة. الأنواع غير الملفات (الموقع، جهات الاتصال، التفاعلات) لا تتأثر.

كل حدث يتضمن كائن contact يحتوي أيضاً على مصفوفة contact_methods[] تسرد جميع معرّفات جهة الاتصال (الأساسي أولاً). يتم الاحتفاظ بحقلَي phone وemail على المستوى الأعلى للتوافق مع الإصدارات السابقة.

تصل تحديدات الرد السريع والقائمة كـ message_type "button". التسمية التوضيحية في "text" ويحمل كائن "meta.button" منظَّم معرّف id والـ payload، مما يتيح توجيه التحديد دون تحليل النص.

عرض مثال على النقر على زر (رد سريع / قائمة)

معرّف ثابت للزر كما تم تحديده عند إرسال الرسالة.

الـ payload الذي أعادته القناة (يطابق id لردود الأزرار السريعة).

التسمية التوضيحية القابلة للقراءة التي رآها المستخدم ونقر عليها.

الرسائل الصادرة التي تتضمن مرفقات ملفات تحتوي على نفس مخطط المرفقات المُثرَاة (id، url، signed_url، content_type، file_size) كالرسائل الواردة.

حقل error موجود على مستوى data (وليس داخل message.meta). يُضمَّن أيضاً كائنا conversation وcontact الكاملان.

أحداث تحديث الحالة (delivered، read) تستخدم كائن conversation أبسط بدون bot_session_id أو حقول الطوابع الزمنية last_*_at. لا يُضمَّن كائن contact_method.

كائنات محادثة البريد الإلكتروني تتضمن حقولاً إضافية: email_integration_id وemail_thread_id لسياق التسلسل.

يتضمن حدث إعادة الفتح حقول محادثة أقل من أحداث المحادثات الأخرى (بدون bot_session_id أو الطوابع الزمنية last_*_at أو subject).

يستخدم contact.updated وcontact.deleted نفس الهيكل. حقل نوع الحدث هو ما يميز بينهما.

احصل على جسم الطلب الخام (قبل تحليل JSON)

احسب HMAC-SHA256 باستخدام سر webhook الخاص بك

استخدم مقارنة آمنة من حيث التوقيت لمنع هجمات التوقيت

عنوان URL الخاص بك يمكن الوصول إليه علنًا (ليس localhost)

شهادة SSL الخاصة بك صالحة (ليست موقعة ذاتيًا)

لا يوجد جدار حماية يحظر عناوين IP الخاصة بـ SendSeven

سر webhook خاطئ (انسخه مرة أخرى من الإعدادات)

خزّن معرف الحدث وتحقق من التكرارات قبل المعالجة

استجب بـ 200 بأسرع ما يمكن (معالجة غير متزامنة)

Webhooks هي استدعاءات HTTP يستخدمها SendSeven لإرسال الأحداث في الوقت الفعلي إلى تطبيقكم. بدلاً من الاستعلام المتكرر عن REST API، يتلقى نقطة الاتصال الخاصة بكم إشعارات فورية عند حدوث شيء مهم — وصول رسالة، أو انتهاء محادثة، أو إنشاء جهة اتصال، أو تغيير حالة التسليم. كل طلب webhook موقّع بـ HMAC لضمان الأمان ويُعاد إرساله تلقائياً عند الفشل مع تأخير تصاعدي أُسّي، مما يضمن عدم فقدان أي حدث.

حساب SendSeven مع قناة متصلة واحدة على الأقل

نقطة اتصال HTTPS عامة قادرة على استقبال طلبات HTTP POST

شهادة SSL صالحة (Let's Encrypt تعمل بشكل ممتاز)

صفحة Webhooks في لوحة تحكم SendSeven مع تمييز زر إضافة نقطة اتصال

مربع حوار إضافة نقطة اتصال مع حقل عنوان HTTPS واشتراكات الأحداث في SendSeven

الأحداث: اختاروا الأحداث التي تريدون استقبالها

نافذة نجاح إنشاء Webhook تعرض المفتاح السري مع زر نسخ

صفحة تفاصيل Webhook تعرض عنوان URL لنقطة الاتصال والأحداث المشترك فيها وسجل التسليم وحالة الصحة في SendSeven

تلقائياً عند إنشاء webhook عبر لوحة التحكم

تلقائياً عند إنشاء webhook عبر API (POST /api/v1/webhook-endpoints)

عند الطلب عبر نقطة اتصال التحقق (POST /api/v1/webhook-endpoints/{id}/verify)

1. إنشاء نقطة نهاية webhook
2. تسجيل webhook في SendSeven
3. اختيار أنواع الأحداث المراد استقبالها
4. معالجة تحدي التحقق من webhook
5. التحقق من توقيع webhook
6. معالجة الأحداث الواردة
7. الاختبار بأحداث تجريبية