Руководство по настройке вебхука

Что такое вебхук?

Webhook позволяет SNSTracker автоматически отправлять уведомления на ваш сервер или в приложение, когда отслеживаемый контент достигает заданных вами пороговых значений. Например, когда у видео значительно увеличиваются просмотры или у канала появляются новые подписчики, SNSTracker отправит уведомление на ваш URL вебхука (обычно в течение 1 минуты).

Пошаговое руководство по настройке

Шаг 1: Подготовьте ваш endpoint вебхука

Перед настройкой в SNSTracker у вас должен быть готов endpoint вебхука. Это URL, который может принимать HTTP POST-запросы.

Варианты для вашего endpoint вебхука:

Ваш собственный сервер: 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: Добавьте целевой вебхук в SNSTracker

Перейдите на страницу Collections
- Войдите в SNSTracker
- Нажмите Collections в левой боковой панели (в разделе Track)
- Или перейдите напрямую: /dashboard/collections
Откройте Manage Notify Targets
- На странице Collections найдите и нажмите кнопку "Manage Notify Targets"
- Откроется диалог управления целями уведомлений
Добавьте новую цель
- Нажмите кнопку "Add Target"
- Появится диалог создания новой цели уведомлений
Выберите тип Webhook
- В диалоге найдите выпадающий список "Type"
- Выберите "Webhook" из вариантов
Введите URL вебхука
- В поле "Webhook URL" введите URL вашего endpoint вебхука
- Пример: https://api.yourcompany.com/webhook
- Важно: URL должен начинаться с https://
Добавьте комментарий (необязательно)
- В поле "Comment" можно добавить заметку, чтобы помнить, для чего этот вебхук
- Пример: "Production webhook for TikTok monitoring"
- Максимум 50 символов
Настройте ключ подписи (необязательно, рекомендуется для продакшена)
- В поле "Extra" можно добавить JSON-объект с ключом подписи:
```
{
  "signature_key": "your-secret-key-here"
}
```
- Этот ключ будет использоваться для проверки подлинности запросов
- Если не указан, SNSTracker будет использовать ваш API-ключ или URL вебхука как ключ подписи
Сохраните цель вебхука
- Нажмите кнопку "Save"
- Ваша цель вебхука создана и готова к использованию

Шаг 3: Настройте правила уведомлений в коллекции

Откройте настройки коллекции
- Вернитесь на страницу Collections
- Найдите коллекцию, для которой хотите настроить уведомления
- Нажмите кнопку Edit (или кликните по названию коллекции, чтобы открыть настройки)
Включите Feed Notify (для видео/постов)
- В настройках коллекции найдите раздел "Feed Notify"
- Переключите "Enable Notifications" в положение ON
- Выберите вашу цель вебхука в выпадающем списке "Notify Targets"
- Выберите "Metrics", которые хотите отслеживать:
  - Views
  - Engagement (likes + comments + shares)
- Задайте значение "Threshold":
  - Введите число (например, 1000), чтобы получать уведомление при увеличении метрики на это значение
  - Установите 0, чтобы уведомлять после каждого успешного обновления
- Нажмите "Save" или "Update"
Включите Channel Notify (для аккаунтов)
- В тех же настройках коллекции найдите раздел "Channel Notify"
- Переключите "Enable Notifications" в положение ON
- Выберите вашу цель вебхука в выпадающем списке "Notify Targets"
- Выберите "Metrics", которые хотите отслеживать:
  - Followers
  - Followings
  - Likes
- Задайте значение "Threshold":
  - Введите число (например, 500), чтобы получать уведомление при увеличении метрики на это значение
  - Установите 0, чтобы уведомлять после каждого успешного обновления
- Нажмите "Save" или "Update"
Проверьте конфигурацию
- Убедитесь, что и цель вебхука, и правила уведомлений сохранены
- Ваш вебхук теперь будет получать уведомления при достижении заданных порогов

Шаг 4: Протестируйте ваш вебхук

Используйте сервис для тестирования (рекомендуется при первом запуске)
- Перейдите на webhook.site
- Скопируйте предоставленный уникальный URL (например, https://webhook.site/unique-id)
- Используйте этот URL как ваш URL вебхука на Шаге 2
- Настройте уведомление с порогом 0 (чтобы срабатывать на любые изменения)
- Дождитесь, пока SNSTracker проверит ваш контент
- Проверьте webhook.site, чтобы увидеть, пришло ли уведомление
Проверьте логи вашего endpoint
- Если используете собственный сервер, проверьте логи сервера
- Ищите входящие POST-запросы от SNSTracker
- Убедитесь, что тело запроса содержит ожидаемые данные
Проверьте формат уведомления
- Уведомление должно быть JSON-объектом со следующими полями:
  - title: Описание уведомления
  - type: Либо "feed", либо "channel"
  - timestamp: Время отправки уведомления
  - data: Массив элементов, которые вызвали уведомление

Как отправляются уведомления вебхука

SNSTracker использует механизм пакетной отправки для оптимизации доставки вебхуков:

Мгновенное обнаружение: Когда отслеживаемый ресурс (feed или channel) успешно обновляется и достигает вашего порога уведомления, он сразу помечается для отправки уведомления.
Пакетное окно 1 минута: Вместо немедленной отправки отдельных уведомлений SNSTracker накапливает все подходящие уведомления в пределах 1-минутного окна.
Объединённая отправка: В конце каждого 1-минутного периода все уведомления из этого окна объединяются в один webhook-запрос и отправляются вместе.

Пример сценария:

В 10:00:15 Feed A достигает порога → помечен
В 10:00:45 Feed B достигает порога → помечен
В 10:01:00 и Feed A, и Feed B отправляются одним webhook-запросом

Преимущества:

Снижает количество 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 для проверки подлинности запросов. Ключ подписи определяется так:

signature_key в поле Extra (если указан)
Ваш первый активный API-ключ (если signature_key не задан)
Ваш URL вебхука (как запасной вариант)

Для продакшена рекомендуется проверять подпись, чтобы убедиться в подлинности запросов.

Устранение неполадок

Вебхук не получает уведомления

Проверьте URL вебхука
- Убедитесь, что URL правильный и доступен
- Убедитесь, что он начинается с https://
- Проверьте URL вручную с помощью POST-запроса
Проверьте настройки уведомлений
- Убедитесь, что уведомления включены в вашей коллекции
- Проверьте, что выбрана цель вебхука
- Убедитесь, что пороги настроены правильно
Проверьте статус endpoint
- Убедитесь, что ваш endpoint работает и доступен
- Проверьте логи сервера на входящие запросы
- Убедитесь, что ваш endpoint возвращает статус успеха (200-299)

Частые проблемы

Проблема: "Webhook URL already exists"
Решение: Каждый URL вебхука можно использовать только один раз на команду. Используйте другой URL или отредактируйте существующую цель.

Проблема: Уведомления не срабатывают
Решение:

Установите порог 0 для теста (уведомляет о любых изменениях)
Дождитесь, пока SNSTracker проверит ваш контент (проверка происходит периодически)
Убедитесь, что ваш контент действительно изменился на величину порога

Проблема: Ошибки таймаута
Решение: Ваш endpoint должен отвечать в течение 30 секунд. Оптимизируйте время ответа вашего endpoint.

Нужна помощь?

Если у вас возникли проблемы:

Убедитесь, что ваш URL вебхука доступен
Проверьте, что настройки уведомлений включены
Убедитесь, что пороги настроены корректно
Обратитесь в поддержку, если проблемы сохраняются

Приятного трекинга! 🚀

Руководство по настройке вебхука

On this page