ГоловнаБлогCallback API Монікор: автоматизація нагород за голоси через webhook і NuVotifier v2
Публікація

Callback API Монікор: автоматизація нагород за голоси через webhook і NuVotifier v2

Налаштуйте миттєві сповіщення на ваш сервер, захистіть endpoint авторизацією та підключіть Minecraft-плагіни без власного бекенду

Автор: Монікор

Уявіть гравця, який щойно проголосував за ваш сервер на Монікор. Він заходить у гру, чекає нагороду, а її немає. Треба написати команду, кликнути адміна, дочекатися його присутності. Половина голосуючих просто йдуть, не отримавши обіцяний бонус, і наступного разу не повертаються голосувати. Це ламає всю систему мотивації.

Альтернатива одна - автоматизувати видачу нагород. І робити це треба миттєво, у момент самого голосу. Саме для цього існує Callback API: подія на платформі ініціює запит на ваш сервер, і нагорода видається до того, як гравець закриє вкладку браузера.

Що таке Callback API простими словами

Callback (зворотний виклик) - це механізм, коли наша платформа сама надсилає вам повідомлення про подію, замість того щоб ви постійно опитували нас. У контексті Монікор це працює так: гравець голосує, лайкає або коментує, і одразу після цього Монікор надсилає POST-запит на вказаний вами URL з усіма деталями події у форматі JSON.

Ваш сервер отримує дані, обробляє їх за вашою логікою і повертає 200 OK. Усе, від моменту голосу до видачі нагороди проходить кілька секунд. Гравець навіть не встигає переключити вкладку.

Чим callback кращий за опитування API

Альтернативний підхід - кожні 30 секунд робити запит до Зовнішнього API і дивитися, чи з'явилися нові голоси. Цей метод називається polling і має кілька серйозних мінусів:

  • Затримка - між голосом і нагородою у середньому 15 секунд (половина інтервалу опитування)
  • Зайві запити - 99% опитувань нічого не повертають, бо нових подій немає
  • Ліміти - щохвилинне опитування швидко з'їдає ліміт у 20 запитів
  • Складність - треба зберігати, на якому id ви зупинилися минулого разу

Callback вирішує всі чотири проблеми одночасно. Гравець голосує - запит миттєво летить до вас. Без події - без запиту. Логіка проста: запам'ятовуєте подію за id, обробляєте, забуваєте.

Структура payload

Коли подія відбувається, ваш endpoint отримує POST-запит з JSON-тілом такого вигляду:

{
  "id": 123,
  "user_id": "discord_user_id",
  "created_at": "2025-01-01T12:00:00Z",
  "action": "vote",
  "category": "minecraft",
  "ip_address": "1.2.3.4",
  "user_nickname": "PlayerName"
}

Кожне поле має зрозумілу роль:

  • id - унікальний ідентифікатор події. Зберігайте його, щоб не обробити одну й ту саму подію двічі у разі повторної доставки
  • user_id - Discord ID гравця. Через нього прив'язуєте подію до акаунта на сервері
  • created_at - точний час події у форматі ISO 8601 з UTC-зоною
  • action - тип події: vote (голос), comment (коментар), like (вподобайка)
  • category - slug категорії сервера (minecraft, discord, gta тощо)
  • ip_address - IP-адреса гравця. Корисно для виявлення накруток
  • user_nickname - нікнейм у Discord або в грі

Безпека: захист endpoint від підробних запитів

Якщо ваш endpoint просто приймає будь-який POST і видає нагороду, через тиждень знайдеться хитрий гравець, який знайде ваш URL і почне слати фейкові події. Захист простий: додайте у налаштувань Callback API заголовок авторизації і токен.

{
  "Authorization": "Bearer your_secret_token"
}

Монікор підставлятиме цей заголовок до кожного запиту автоматично. На вашому endpoint перевіряєте: заголовок є і токен правильний - обробляєте подію, ні - повертаєте 401 і записуєте у лог. Без правильного токена сторонній не зможе підробити голос, навіть якщо знає URL вашого endpoint.

Окремий шлях для Minecraft: NuVotifier v2

Більшість Minecraft-серверів давно використовують плагін NuVotifier для прийому голосів з різних моніторингів. Він стандартизує формат і дозволяє іншим плагінам (наприклад, VotingPlugin) реагувати на голоси за вказаною конфігурацією.

Монікор підтримує цей протокол з коробки. Увімкніть опцію NuVotifier v2 у налаштуваннях, вкажіть хост, порт (зазвичай 8192) і токен з конфігу плагіна, і платформа надсилатиме Vote-пакет напряму на ваш Minecraft-сервер. Жодного власного бекенду, жодних PHP-скриптів і Node.js-сервісів.

Що це дає на практиці:

  • Сумісність з усіма популярними плагінами нагород: VotingPlugin, GAListener, SuperbVote
  • Налаштування нагород повністю на стороні Minecraft-сервера через звичайні YAML-конфіги
  • Жодного хостингу веб-сервера для callback - усе йде напряму TCP-з'єднанням
  • Підтримка декількох сайтів моніторингу одночасно з однаковою логікою нагород

Що можна побудувати на callback

Тепер, коли ви знаєте, як це працює, ось ідеї для впровадження:

  • Автоматична видача валюти - за голос +100 монет, за лайк +50, за коментар +200
  • Накопичувальна система - кожні 10 голосів дають VIP-роль на тиждень
  • Discord-сповіщення - канал #votes показує, хто щойно проголосував
  • Лідерборд активності - таблиця найактивніших гравців з нагородами раз на місяць
  • Email-розсилка - щотижневий дайджест адміну з найбільш активними коментаторами
  • Антинакрутка - аналізуєте IP та частоту голосів, виявляєте спроби накруток
  • Інтеграція з CRM - кожен новий коментар створює тикет у вашій системі підтримки

Тестер доставки

На сторінці інструмента є кнопка тестового запиту. Натискаєте, Монікор надсилає на ваш URL фіктивну подію з усіма реальними полями. Якщо ваш endpoint відповів 200 OK, усе налаштовано правильно. Якщо ні, бачите помилку і виправляєте до того, як перший реальний голос ризикне загубитися.

Рекомендуємо тестувати після кожної зміни на боці вашого сервера: переніс хостинг, оновили SSL-сертифікат, змінили токен у конфігу. П'ять секунд тесту замість години розбиратися, чому гравці пишуть про відсутні нагороди.

Поширені помилки під час налаштування

Endpoint повертає 200, але нагорода не йде. Перевірте логи свого сервера. Швидше за все, ви приймаєте запит, але парсите JSON неправильно або ваша логіка нарахування ламається на null-значеннях у полі user_nickname.

Часті 502/504 у логах. Ваш endpoint занадто довго обробляє запит. Швидко відповідайте 200 OK, а важку логіку (наприклад, видачу великої кількості предметів) виконуйте у фоновій черзі.

Дублювання нагород. Не зберігаєте id події. Якщо Монікор повторно надішле запит через timeout мережі, ви видасте нагороду двічі. Завжди робіть deduplication за полем id.

NuVotifier не приймає пакет. Перевірте, що порт відкритий у фаєрволі і токен у конфігу плагіна повністю збігається з тим, що вказано в Монікор.

Поширені запитання

Що відбувається, якщо мій сервер вимкнений у момент події? Монікор робить кілька повторних спроб з паузами. Якщо протягом усіх спроб ваш сервер не відповів, подія залишається у логах платформи, але не доставляється повторно через години.

Чи можна налаштувати декілька callback URL одночасно? На один сервер один URL. Якщо потрібно роздвоїти потік (наприклад, у Discord-канал і в Minecraft-плагін), використовуйте простий проксі на своєму бекенді.

Чи безпечно передавати IP гравця через webhook? Так, це публічна метаінформація запиту, з якого було проголосовано. Зберігайте її відповідно до GDPR і політики конфіденційності вашого сервера.

Чи відрізняється формат для action=like і action=comment? Структура однакова, відрізняється лише значення поля action. Це дозволяє обробляти всі події одним обробником і галужитися всередині.

Підсумок

Callback API перетворює Монікор з пасивного моніторингу на активного учасника життя вашого сервера. Гравець натискає "Голосувати" - і за секунди отримує нагороду. Спільнота бачить, що активність винагороджується. Адмін перестає бути вузьким місцем у видачі бонусів. Налаштування забирає півгодини, ефект тримається роками.

Назад до блогу