دليل إعداد Webhook
ما هو Webhook؟
يسمح Webhook لـ SNSTracker بإرسال إشعارات تلقائية إلى خادمك أو تطبيقك عند وصول المحتوى المراقَب إلى العتبات التي قمت بتكوينها. على سبيل المثال، عندما ترتفع مشاهدات فيديو بشكل ملحوظ، أو عندما تحصل قناة على متابعين جدد، سيرسل SNSTracker إشعارًا إلى عنوان Webhook الخاص بك (عادةً خلال دقيقة واحدة).
دليل الإعداد خطوة بخطوة
الخطوة 1: جهّز نقطة نهاية Webhook
قبل الإعداد في SNSTracker، تحتاج إلى تجهيز نقطة نهاية Webhook. هذا عنوان URL يمكنه استقبال طلبات HTTP POST.
خيارات نقطة نهاية الـ Webhook الخاصة بك:
- خادمك الخاص:
https://api.yourcompany.com/webhook - الدوال السحابية: AWS Lambda، Google Cloud Functions، Azure Functions، إلخ.
- منصات الأتمتة: Zapier، Make.com، n8n، إلخ.
- خدمات الاختبار: webhook.site (للاختبار فقط)
المتطلبات:
- يجب استخدام HTTPS (يبدأ عنوان URL بـ
https://) - يجب قبول طلبات POST
- ينبغي إرجاع رمز حالة HTTP 200-299 عند النجاح
الخطوة 2: إضافة هدف Webhook في SNSTracker
-
الانتقال إلى صفحة المجموعات
- سجّل الدخول إلى SNSTracker
- انقر Collections في الشريط الجانبي الأيسر (ضمن قسم Track)
- أو انتقل مباشرة إلى:
/dashboard/collections
-
فتح إدارة أهداف الإشعارات
- في صفحة المجموعات، اعثر على زر "Manage Notify Targets" وانقر عليه
- سيُفتح مربع حوار لإدارة أهداف الإشعارات
-
إضافة هدف جديد
- انقر زر "Add Target"
- سيظهر مربع حوار لإنشاء هدف إشعارات جديد
-
اختيار نوع Webhook
- في مربع الحوار، ابحث عن القائمة المنسدلة "Type"
- اختر "Webhook" من الخيارات
-
إدخال عنوان Webhook
- في حقل "Webhook URL" أدخل عنوان URL لنقطة النهاية الخاصة بك
- مثال:
https://api.yourcompany.com/webhook - مهم: يجب أن يبدأ عنوان URL بـ
https://
-
إضافة تعليق (اختياري)
- في حقل "Comment" يمكنك إضافة ملاحظة لتتذكر الغرض من هذا الـ webhook
- مثال: "Webhook للإنتاج لمراقبة TikTok"
- الحد الأقصى 50 حرفًا
-
تهيئة مفتاح التوقيع (اختياري، موصى به للإنتاج)
- في حقل "Extra" يمكنك إضافة كائن JSON يحتوي على مفتاح توقيع:
{ "signature_key": "your-secret-key-here" }- سيُستخدم هذا المفتاح للتحقق من أن الطلبات أصلية
- إذا لم يُقدَّم، سيستخدم SNSTracker مفتاح API الخاص بك أو عنوان webhook كمفتاح توقيع
-
حفظ هدف الـ webhook
- انقر زر "Save"
- تم الآن إنشاء هدف الـ webhook وهو جاهز للاستخدام
الخطوة 3: إعداد قواعد الإشعارات داخل المجموعة
-
فتح إعدادات المجموعة
- ارجع إلى صفحة المجموعات
- اعثر على المجموعة التي تريد إعداد الإشعارات لها
- انقر زر Edit (أو انقر على اسم المجموعة لفتح الإعدادات)
-
تفعيل إشعارات الـ Feed (للفيديوهات/المنشورات)
- في إعدادات المجموعة، اعثر على قسم "Feed Notify"
- فعّل مفتاح "Enable Notifications" إلى وضع التشغيل
- اختر هدف الـ webhook من القائمة المنسدلة "Notify Targets"
- اختر "Metrics" التي تريد مراقبتها:
- Views
- Engagement (likes + comments + shares)
- حدّد قيمة "Threshold":
- أدخل رقمًا (مثل 1000) لإرسال إشعار عند زيادة المقياس بهذا المقدار
- اضبطه على 0 للإشعار بعد كل تحديث ناجح
- انقر "Save" أو "Update"
-
تفعيل إشعارات القناة (للحسابات)
- في نفس إعدادات المجموعة، اعثر على قسم "Channel Notify"
- فعّل مفتاح "Enable Notifications" إلى وضع التشغيل
- اختر هدف الـ webhook من القائمة المنسدلة "Notify Targets"
- اختر "Metrics" التي تريد مراقبتها:
- Followers
- Followings
- Likes
- حدّد قيمة "Threshold":
- أدخل رقمًا (مثل 500) لإرسال إشعار عند زيادة المقياس بهذا المقدار
- اضبطه على 0 للإشعار بعد كل تحديث ناجح
- انقر "Save" أو "Update"
-
التحقق من الإعداد
- تأكّد من حفظ كل من هدف الـ webhook وقواعد الإشعارات
- سيبدأ الـ webhook الآن في تلقي الإشعارات عند استيفاء العتبات المُعدّة
الخطوة 4: اختبار الـ Webhook
-
استخدم خدمة اختبار (موصى بها للإعداد لأول مرة)
- زر webhook.site
- انسخ عنوان URL الفريد المُقدَّم (مثال:
https://webhook.site/unique-id) - استخدم هذا العنوان كعنوان webhook في الخطوة 2
- اضبط إشعارًا بعتبة 0 (للإطلاق عند أي تغيير)
- انتظر حتى يتحقق SNSTracker من المحتوى
- تحقق من webhook.site لمعرفة ما إذا تلقيت الإشعار
-
تحقق من سجلات نقطة النهاية لديك
- إذا كنت تستخدم خادمك الخاص، راجع سجلات الخادم
- ابحث عن طلبات POST الواردة من SNSTracker
- تحقق أن جسم الطلب يحتوي البيانات المتوقعة
-
التحقق من تنسيق الإشعار
- يجب أن يكون الإشعار كائن JSON يحتوي على:
title: وصف الإشعارtype: إما "feed" أو "channel"timestamp: وقت إرسال الإشعارdata: مصفوفة العناصر التي تسببت في الإشعار
- يجب أن يكون الإشعار كائن JSON يحتوي على:
كيف يتم إرسال إشعارات الـ 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 للتحقق من أصالة الطلب. يتم تحديد مفتاح التوقيع وفقًا لـ:
signature_keyفي حقل Extra (إن وُجد)- أول مفتاح API نشط لديك (إذا لم يتم تعيين signature_key)
- عنوان webhook الخاص بك (كخيار احتياطي)
للاستخدام في الإنتاج، يُنصح بالتحقق من التوقيع لضمان أن الطلبات أصلية.
استكشاف الأخطاء وإصلاحها
الـ Webhook لا يستقبل إشعارات
-
تحقق من عنوان webhook
- تأكد أن العنوان صحيح ويمكن الوصول إليه
- تأكد أنه يبدأ بـ
https:// - اختبر العنوان يدويًا بطلب POST
-
تحقق من إعدادات الإشعارات
- تأكد أن الإشعارات مفعّلة في المجموعة
- تحقق من اختيار هدف الـ webhook
- تأكد أن العتبات مضبوطة بشكل صحيح
-
تحقق من حالة نقطة النهاية
- تأكد أن نقطة النهاية لديك تعمل ويمكن الوصول إليها
- راجع سجلات الخادم للطلبات الواردة
- تأكد أن نقطة النهاية تُرجع حالة نجاح (200-299)
مشكلات شائعة
المشكلة: "Webhook URL already exists"
الحل: يمكن استخدام كل عنوان webhook مرة واحدة فقط لكل فريق. استخدم عنوانًا مختلفًا أو قم بتحرير الهدف الحالي.
المشكلة: عدم تشغيل الإشعارات
الحل:
- اضبط العتبة على 0 للاختبار (إشعار عند أي تغيير)
- انتظر حتى يتحقق SNSTracker من المحتوى (يحدث التحقق دوريًا)
- تأكد أن المحتوى تغيّر فعليًا بمقدار العتبة
المشكلة: أخطاء المهلة الزمنية
الحل: يجب أن تستجيب نقطة النهاية خلال 30 ثانية. حسّن زمن استجابة نقطة النهاية لديك.
هل تحتاج مساعدة؟
إذا واجهت مشاكل:
- تحقق من إمكانية الوصول إلى عنوان webhook
- تحقق أن إعدادات الإشعارات مفعلة
- تأكد أن العتبات مضبوطة بشكل صحيح
- تواصل مع الدعم إذا استمرت المشكلة
تتبّع موفق! 🚀