راهنمای پیکربندی وبهوک

وبهوک چیست؟

وبهوک به SNSTracker اجازه می‌دهد وقتی محتوای پایش‌شده به آستانه‌های تنظیم‌شده شما برسد، به‌صورت خودکار به سرور یا اپلیکیشن شما اعلان ارسال کند. برای مثال، وقتی بازدید یک ویدئو به‌طور قابل‌توجهی افزایش پیدا کند یا یک کانال دنبال‌کننده‌های جدید بگیرد، SNSTracker یک اعلان به آدرس وبهوک شما می‌فرستد (معمولاً ظرف 1 دقیقه).

راهنمای پیکربندی مرحله‌به‌مرحله

مرحله 1: آماده‌سازی Endpoint وبهوک

قبل از پیکربندی در SNSTracker، باید یک endpoint وبهوک آماده داشته باشید. این یک URL است که می‌تواند درخواست‌های HTTP POST را دریافت کند.

گزینه‌های endpoint وبهوک شما:

  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: افزودن هدف وبهوک در SNSTracker

  1. رفتن به صفحه Collections

    • وارد SNSTracker شوید
    • در نوار کناری سمت چپ روی Collections (زیر بخش Track) کلیک کنید
    • یا مستقیم بروید به: /dashboard/collections
  2. باز کردن Manage Notify Targets

    • در صفحه Collections، دکمه "Manage Notify Targets" را پیدا کرده و کلیک کنید
    • این کار پنجره مدیریت اهداف اعلان را باز می‌کند
  3. افزودن یک هدف جدید

    • روی دکمه "Add Target" کلیک کنید
    • یک پنجره برای ایجاد هدف اعلان جدید ظاهر می‌شود
  4. انتخاب نوع Webhook

    • در پنجره، منوی کشویی "Type" را پیدا کنید
    • از گزینه‌ها "Webhook" را انتخاب کنید
  5. وارد کردن URL وبهوک

    • در فیلد "Webhook URL"، آدرس endpoint وبهوک خود را وارد کنید
    • مثال: https://api.yourcompany.com/webhook
    • مهم: URL باید با https:// شروع شود
  6. افزودن توضیح (اختیاری)

    • در فیلد "Comment" می‌توانید یادداشتی برای به‌خاطر سپردن کاربرد این وبهوک اضافه کنید
    • مثال: "Production webhook for TikTok monitoring"
    • حداکثر 50 کاراکتر
  7. پیکربندی کلید امضا (اختیاری، برای پروداکشن توصیه می‌شود)

    • در فیلد "Extra" می‌توانید یک شیء JSON با کلید امضا اضافه کنید:
    {
      "signature_key": "your-secret-key-here"
    }
    • از این کلید برای تأیید اصالت درخواست‌ها استفاده می‌شود
    • اگر ارائه نشود، SNSTracker از کلید API یا URL وبهوک شما به‌عنوان کلید امضا استفاده می‌کند
  8. ذخیره هدف وبهوک

    • روی دکمه "Save" کلیک کنید
    • هدف وبهوک شما اکنون ایجاد شده و آماده استفاده است

مرحله 3: پیکربندی قوانین اعلان در Collection

  1. باز کردن تنظیمات Collection

    • به صفحه Collections برگردید
    • کالکشنی را که می‌خواهید اعلان‌ها برای آن تنظیم شود پیدا کنید
    • روی دکمه Edit کلیک کنید (یا روی نام کالکشن کلیک کنید تا تنظیمات باز شود)
  2. فعال‌سازی Feed Notify (برای ویدئوها/پست‌ها)

    • در تنظیمات کالکشن، بخش "Feed Notify" را پیدا کنید
    • سوییچ "Enable Notifications" را روشن کنید
    • از منوی کشویی "Notify Targets" هدف وبهوک خود را انتخاب کنید
    • "Metrics" موردنظر برای پایش را انتخاب کنید:
      • Views
      • Engagement (likes + comments + shares)
    • مقدار "Threshold" را تنظیم کنید:
      • یک عدد وارد کنید (مثلاً 1000) تا وقتی معیار به این مقدار افزایش یافت اعلان ارسال شود
      • روی 0 بگذارید تا بعد از هر به‌روزرسانی موفق اعلان ارسال شود
    • روی "Save" یا "Update" کلیک کنید
  3. فعال‌سازی Channel Notify (برای حساب‌ها)

    • در همان تنظیمات کالکشن، بخش "Channel Notify" را پیدا کنید
    • سوییچ "Enable Notifications" را روشن کنید
    • از منوی کشویی "Notify Targets" هدف وبهوک خود را انتخاب کنید
    • "Metrics" موردنظر برای پایش را انتخاب کنید:
      • Followers
      • Followings
      • Likes
    • مقدار "Threshold" را تنظیم کنید:
      • یک عدد وارد کنید (مثلاً 500) تا وقتی معیار به این مقدار افزایش یافت اعلان ارسال شود
      • روی 0 بگذارید تا بعد از هر به‌روزرسانی موفق اعلان ارسال شود
    • روی "Save" یا "Update" کلیک کنید
  4. تأیید پیکربندی

    • مطمئن شوید هم هدف وبهوک و هم قوانین اعلان ذخیره شده‌اند
    • اکنون وقتی آستانه‌های تنظیم‌شده محقق شوند، وبهوک شما اعلان دریافت می‌کند

مرحله 4: تست وبهوک

  1. استفاده از سرویس تست (برای راه‌اندازی اولیه توصیه می‌شود)

    • به webhook.site بروید
    • URL منحصربه‌فرد ارائه‌شده را کپی کنید (مثلاً https://webhook.site/unique-id)
    • از این URL به‌عنوان وبهوک خود در مرحله 2 استفاده کنید
    • یک اعلان با آستانه 0 پیکربندی کنید (برای فعال شدن با هر تغییر)
    • منتظر بمانید تا SNSTracker محتوای شما را بررسی کند
    • در webhook.site بررسی کنید که آیا اعلان را دریافت کرده‌اید یا نه
  2. بررسی لاگ‌های endpoint

    • اگر از سرور خودتان استفاده می‌کنید، لاگ‌های سرور را بررسی کنید
    • به دنبال درخواست‌های POST ورودی از SNSTracker باشید
    • مطمئن شوید بدنه درخواست شامل داده‌های مورد انتظار است
  3. بررسی قالب اعلان

    • اعلان باید یک شیء JSON باشد با:
      • title: توضیح اعلان
      • type: یا "feed" یا "channel"
      • timestamp: زمان ارسال اعلان
      • data: آرایه‌ای از مواردی که اعلان را فعال کرده‌اند

اعلان‌های وبهوک چگونه ارسال می‌شوند؟

SNSTracker برای بهینه‌سازی ارسال وبهوک از مکانیزم تجمیع استفاده می‌کند:

  • تشخیص فوری: وقتی یک منبع پایش‌شده (feed یا channel) با موفقیت تازه‌سازی شود و آستانه اعلان شما را برآورده کند، فوراً برای اعلان علامت‌گذاری می‌شود.

  • پنجره تجمیع 1 دقیقه‌ای: به جای ارسال فوری اعلان‌های جداگانه، SNSTracker همه اعلان‌های واجد شرایط را در یک پنجره 1 دقیقه‌ای جمع‌آوری می‌کند.

  • ارسال تجمیعی: در پایان هر بازه 1 دقیقه‌ای، همه اعلان‌های آن پنجره در یک درخواست وبهوک ادغام شده و با هم ارسال می‌شوند.

سناریوی نمونه:

  • ساعت 10:00:15، Feed A به آستانه می‌رسد → علامت‌گذاری می‌شود
  • ساعت 10:00:45، Feed B به آستانه می‌رسد → علامت‌گذاری می‌شود
  • ساعت 10:01:00، هر دو Feed A و Feed B در یک درخواست وبهوک ارسال می‌شوند

مزایا:

  • تعداد درخواست‌های HTTP به endpoint شما را کاهش می‌دهد
  • کارایی را بهبود می‌دهد و بار سرور را کم می‌کند
  • از اسپم اعلان‌ها در زمان تغییرات سریع داده جلوگیری می‌کند
  • همه اعلان‌ها در بازه تجمیع در آرایه data قرار می‌گیرند

نکته: حداکثر تأخیر بین رسیدن منبع به آستانه و ارسال وبهوک 1 دقیقه است. این موضوع اعلان‌های تقریباً بلادرنگ را در کنار حفظ کارایی سیستم تضمین می‌کند.

چه داده‌ای دریافت می‌کنید؟

وقتی اعلان فعال شود، یک درخواست 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: افزایش تعامل (لایک + کامنت + اشتراک‌گذاری)

فیلدهای داده اعلان Channel

  • 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. URL وبهوک شما (به‌عنوان حالت پشتیبان)

برای استفاده در محیط پروداکشن، توصیه می‌شود امضا را بررسی کنید تا مطمئن شوید درخواست‌ها معتبر هستند.

رفع اشکال

وبهوک اعلان دریافت نمی‌کند

  1. بررسی URL وبهوک

    • مطمئن شوید URL درست و قابل دسترس است
    • مطمئن شوید با https:// شروع می‌شود
    • URL را با یک درخواست POST به‌صورت دستی تست کنید
  2. بررسی تنظیمات اعلان

    • مطمئن شوید اعلان‌ها در کالکشن شما فعال هستند
    • بررسی کنید که هدف وبهوک انتخاب شده باشد
    • مطمئن شوید آستانه‌ها درست تنظیم شده‌اند
  3. بررسی وضعیت endpoint

    • مطمئن شوید endpoint شما در حال اجرا و قابل دسترس است
    • لاگ‌های سرور را برای درخواست‌های ورودی بررسی کنید
    • مطمئن شوید endpoint شما وضعیت موفقیت (200-299) برمی‌گرداند

مشکلات رایج

مشکل: "Webhook URL already exists"
راه‌حل: هر URL وبهوک فقط یک‌بار در هر تیم قابل استفاده است. از یک URL متفاوت استفاده کنید یا هدف موجود را ویرایش کنید.

مشکل: اعلان‌ها فعال نمی‌شوند
راه‌حل:

  • برای تست آستانه را روی 0 بگذارید (با هر تغییر اعلان می‌دهد)
  • منتظر بمانید تا SNSTracker محتوای شما را بررسی کند (بررسی‌ها به‌صورت دوره‌ای انجام می‌شود)
  • مطمئن شوید محتوای شما واقعاً به اندازه آستانه تغییر کرده است

مشکل: خطاهای Timeout
راه‌حل: endpoint شما باید ظرف 30 ثانیه پاسخ دهد. زمان پاسخ endpoint را بهینه کنید.

کمک نیاز دارید؟

اگر با مشکل روبه‌رو شدید:

  1. مطمئن شوید URL وبهوک شما قابل دسترس است
  2. بررسی کنید که تنظیمات اعلان فعال باشند
  3. مطمئن شوید آستانه‌ها درست پیکربندی شده‌اند
  4. اگر مشکل ادامه داشت، با پشتیبانی تماس بگیرید

ردگیری خوش! 🚀