دليل إعداد Webhook

ما هو Webhook؟

يسمح Webhook لـ SNSTracker بإرسال إشعارات تلقائية إلى خادمك أو تطبيقك عند وصول المحتوى المراقَب إلى العتبات التي قمت بتكوينها. على سبيل المثال، عندما ترتفع مشاهدات فيديو بشكل ملحوظ، أو عندما تحصل قناة على متابعين جدد، سيرسل SNSTracker إشعارًا إلى عنوان Webhook الخاص بك (عادةً خلال دقيقة واحدة).

دليل الإعداد خطوة بخطوة

الخطوة 1: جهّز نقطة نهاية Webhook

قبل الإعداد في SNSTracker، تحتاج إلى تجهيز نقطة نهاية Webhook. هذا عنوان URL يمكنه استقبال طلبات HTTP POST.

خيارات نقطة نهاية الـ Webhook الخاصة بك:

  1. خادمك الخاص: https://api.yourcompany.com/webhook
  2. الدوال السحابية: AWS Lambda، Google Cloud Functions، Azure Functions، إلخ.
  3. منصات الأتمتة: Zapier، Make.com، n8n، إلخ.
  4. خدمات الاختبار: webhook.site (للاختبار فقط)

المتطلبات:

  • يجب استخدام HTTPS (يبدأ عنوان URL بـ https://)
  • يجب قبول طلبات POST
  • ينبغي إرجاع رمز حالة HTTP 200-299 عند النجاح

الخطوة 2: إضافة هدف Webhook في SNSTracker

  1. الانتقال إلى صفحة المجموعات

    • سجّل الدخول إلى SNSTracker
    • انقر Collections في الشريط الجانبي الأيسر (ضمن قسم Track)
    • أو انتقل مباشرة إلى: /dashboard/collections
  2. فتح إدارة أهداف الإشعارات

    • في صفحة المجموعات، اعثر على زر "Manage Notify Targets" وانقر عليه
    • سيُفتح مربع حوار لإدارة أهداف الإشعارات
  3. إضافة هدف جديد

    • انقر زر "Add Target"
    • سيظهر مربع حوار لإنشاء هدف إشعارات جديد
  4. اختيار نوع Webhook

    • في مربع الحوار، ابحث عن القائمة المنسدلة "Type"
    • اختر "Webhook" من الخيارات
  5. إدخال عنوان Webhook

    • في حقل "Webhook URL" أدخل عنوان URL لنقطة النهاية الخاصة بك
    • مثال: https://api.yourcompany.com/webhook
    • مهم: يجب أن يبدأ عنوان URL بـ https://
  6. إضافة تعليق (اختياري)

    • في حقل "Comment" يمكنك إضافة ملاحظة لتتذكر الغرض من هذا الـ webhook
    • مثال: "Webhook للإنتاج لمراقبة TikTok"
    • الحد الأقصى 50 حرفًا
  7. تهيئة مفتاح التوقيع (اختياري، موصى به للإنتاج)

    • في حقل "Extra" يمكنك إضافة كائن JSON يحتوي على مفتاح توقيع:
    {
      "signature_key": "your-secret-key-here"
    }
    • سيُستخدم هذا المفتاح للتحقق من أن الطلبات أصلية
    • إذا لم يُقدَّم، سيستخدم SNSTracker مفتاح API الخاص بك أو عنوان webhook كمفتاح توقيع
  8. حفظ هدف الـ webhook

    • انقر زر "Save"
    • تم الآن إنشاء هدف الـ webhook وهو جاهز للاستخدام

الخطوة 3: إعداد قواعد الإشعارات داخل المجموعة

  1. فتح إعدادات المجموعة

    • ارجع إلى صفحة المجموعات
    • اعثر على المجموعة التي تريد إعداد الإشعارات لها
    • انقر زر Edit (أو انقر على اسم المجموعة لفتح الإعدادات)
  2. تفعيل إشعارات الـ Feed (للفيديوهات/المنشورات)

    • في إعدادات المجموعة، اعثر على قسم "Feed Notify"
    • فعّل مفتاح "Enable Notifications" إلى وضع التشغيل
    • اختر هدف الـ webhook من القائمة المنسدلة "Notify Targets"
    • اختر "Metrics" التي تريد مراقبتها:
      • Views
      • Engagement (likes + comments + shares)
    • حدّد قيمة "Threshold":
      • أدخل رقمًا (مثل 1000) لإرسال إشعار عند زيادة المقياس بهذا المقدار
      • اضبطه على 0 للإشعار بعد كل تحديث ناجح
    • انقر "Save" أو "Update"
  3. تفعيل إشعارات القناة (للحسابات)

    • في نفس إعدادات المجموعة، اعثر على قسم "Channel Notify"
    • فعّل مفتاح "Enable Notifications" إلى وضع التشغيل
    • اختر هدف الـ webhook من القائمة المنسدلة "Notify Targets"
    • اختر "Metrics" التي تريد مراقبتها:
      • Followers
      • Followings
      • Likes
    • حدّد قيمة "Threshold":
      • أدخل رقمًا (مثل 500) لإرسال إشعار عند زيادة المقياس بهذا المقدار
      • اضبطه على 0 للإشعار بعد كل تحديث ناجح
    • انقر "Save" أو "Update"
  4. التحقق من الإعداد

    • تأكّد من حفظ كل من هدف الـ webhook وقواعد الإشعارات
    • سيبدأ الـ webhook الآن في تلقي الإشعارات عند استيفاء العتبات المُعدّة

الخطوة 4: اختبار الـ Webhook

  1. استخدم خدمة اختبار (موصى بها للإعداد لأول مرة)

    • زر webhook.site
    • انسخ عنوان URL الفريد المُقدَّم (مثال: https://webhook.site/unique-id)
    • استخدم هذا العنوان كعنوان webhook في الخطوة 2
    • اضبط إشعارًا بعتبة 0 (للإطلاق عند أي تغيير)
    • انتظر حتى يتحقق SNSTracker من المحتوى
    • تحقق من webhook.site لمعرفة ما إذا تلقيت الإشعار
  2. تحقق من سجلات نقطة النهاية لديك

    • إذا كنت تستخدم خادمك الخاص، راجع سجلات الخادم
    • ابحث عن طلبات POST الواردة من SNSTracker
    • تحقق أن جسم الطلب يحتوي البيانات المتوقعة
  3. التحقق من تنسيق الإشعار

    • يجب أن يكون الإشعار كائن JSON يحتوي على:
      • title: وصف الإشعار
      • type: إما "feed" أو "channel"
      • timestamp: وقت إرسال الإشعار
      • data: مصفوفة العناصر التي تسببت في الإشعار

كيف يتم إرسال إشعارات الـ Webhook

يستخدم SNSTracker آلية التجميع لتحسين تسليم الـ webhook:

  • اكتشاف فوري: عندما يتم تحديث مورد مُراقَب (feed أو channel) بنجاح ويحقق عتبة الإشعار، يتم تمييزه فورًا للإشعار.

  • نافذة تجميع لمدة دقيقة واحدة: بدلًا من إرسال إشعارات فردية فورًا، يجمع SNSTracker جميع الإشعارات المؤهلة ضمن نافذة مدتها دقيقة واحدة.

  • إرسال موحّد: في نهاية كل فترة دقيقة واحدة، يتم دمج جميع الإشعارات ضمن تلك النافذة في طلب webhook واحد وإرسالها معًا.

مثال على السيناريو:

  • الساعة 10:00:15، تحقق Feed A العتبة → تم تمييزه
  • الساعة 10:00:45، تحقق Feed B العتبة → تم تمييزه
  • الساعة 10:01:00، يُرسل كل من Feed A وFeed B في طلب webhook واحد

الفوائد:

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

ملاحظة: أقصى تأخير بين وصول المورد للعتبة وإرسال الـ webhook هو دقيقة واحدة. هذا يضمن إشعارات شبه فورية مع الحفاظ على كفاءة النظام.

ما البيانات التي ستتلقاها؟

عند تشغيل إشعار، ستتلقى طلب POST ببيانات JSON مثل هذه:

{
  "title": "SNSTracker Notification: Feed Views Increased",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

حقول بيانات إشعار الـ Feed

  • feed_id: معرّف فريد
  • url: رابط مباشر للفيديو/المنشور
  • platform_name: المنصة (TikTok، Instagram، إلخ.)
  • title: عنوان المحتوى
  • description: وصف المحتوى
  • author_username: اسم المستخدم للمنشئ
  • author_nickname: الاسم الظاهر للمنشئ
  • view_count: إجمالي المشاهدات
  • like_count: إجمالي الإعجابات
  • comment_count: إجمالي التعليقات
  • share_count: إجمالي المشاركات
  • changed_views: زيادة المشاهدات منذ آخر فحص
  • changed_engagement: زيادة التفاعل (إعجابات + تعليقات + مشاركات)

حقول بيانات إشعار القناة

  • id: معرّف فريد للقناة
  • channel_url: رابط مباشر للقناة/الملف الشخصي
  • platform_name: اسم المنصة
  • nickname: الاسم الظاهر
  • username: اسم المستخدم/المعرّف
  • followers: إجمالي المتابعين
  • followings: إجمالي الحسابات التي يتابعها
  • likes: إجمالي الإعجابات
  • changed_followers: زيادة المتابعين منذ آخر فحص
  • changed_followings: زيادة المتابَعين منذ آخر فحص
  • changed_likes: زيادة الإعجابات منذ آخر فحص

الأمان: التحقق من التوقيع

يتضمن SNSTracker توقيعًا في ترويسة X-Signature للتحقق من أصالة الطلب. يتم تحديد مفتاح التوقيع وفقًا لـ:

  1. signature_key في حقل Extra (إن وُجد)
  2. أول مفتاح API نشط لديك (إذا لم يتم تعيين signature_key)
  3. عنوان webhook الخاص بك (كخيار احتياطي)

للاستخدام في الإنتاج، يُنصح بالتحقق من التوقيع لضمان أن الطلبات أصلية.

استكشاف الأخطاء وإصلاحها

الـ Webhook لا يستقبل إشعارات

  1. تحقق من عنوان webhook

    • تأكد أن العنوان صحيح ويمكن الوصول إليه
    • تأكد أنه يبدأ بـ https://
    • اختبر العنوان يدويًا بطلب POST
  2. تحقق من إعدادات الإشعارات

    • تأكد أن الإشعارات مفعّلة في المجموعة
    • تحقق من اختيار هدف الـ webhook
    • تأكد أن العتبات مضبوطة بشكل صحيح
  3. تحقق من حالة نقطة النهاية

    • تأكد أن نقطة النهاية لديك تعمل ويمكن الوصول إليها
    • راجع سجلات الخادم للطلبات الواردة
    • تأكد أن نقطة النهاية تُرجع حالة نجاح (200-299)

مشكلات شائعة

المشكلة: "Webhook URL already exists"
الحل: يمكن استخدام كل عنوان webhook مرة واحدة فقط لكل فريق. استخدم عنوانًا مختلفًا أو قم بتحرير الهدف الحالي.

المشكلة: عدم تشغيل الإشعارات
الحل:

  • اضبط العتبة على 0 للاختبار (إشعار عند أي تغيير)
  • انتظر حتى يتحقق SNSTracker من المحتوى (يحدث التحقق دوريًا)
  • تأكد أن المحتوى تغيّر فعليًا بمقدار العتبة

المشكلة: أخطاء المهلة الزمنية
الحل: يجب أن تستجيب نقطة النهاية خلال 30 ثانية. حسّن زمن استجابة نقطة النهاية لديك.

هل تحتاج مساعدة؟

إذا واجهت مشاكل:

  1. تحقق من إمكانية الوصول إلى عنوان webhook
  2. تحقق أن إعدادات الإشعارات مفعلة
  3. تأكد أن العتبات مضبوطة بشكل صحيح
  4. تواصل مع الدعم إذا استمرت المشكلة

تتبّع موفق! 🚀