Побудуйте систему вебхук-сповіщень для Hyperliquid за 30 хвилин

Ваш цикл опитування запускається кожні п'ять хвилин, отримує ті самі дані когорт, порівнює їх із попереднім знімком і вирішує, що нічого не змінилося. Тим часом когорта Money Printer щойно перевернулася в нетто-шорт по ETH, навколо рівня $3,800 сформувався кластер ліквідацій, а три Leviathan відкрили свіжі лонги по SOL. До моменту, коли прийде ваш наступний запит, рух вже врахований у ціні.

Опитування є стандартним підходом, бо це найпростіший паттерн. Ви задаєте інтервал, звертаєтеся до ендпоінту, порівнюєте відповідь і вважаєте справу закритою. Але за простоту ви платите затримкою, даремними API-викликами на незмінені дані і відчуттям, що щось важливе сталося між вашими двома останніми запитами. Вебхуки перевертають цю модель. Замість того щоб питати "чи щось змінилося?" кожні кілька хвилин, сервер повідомляє вас у ту ж мить, коли це відбувається.

Доставка вебхуків у HyperTracker доступна на тарифах Flow ($799/міс) і Stream ($1,999/міс). Ви реєструєте URL, налаштовуєте події, які вас цікавлять, і наша інфраструктура надсилає підписаний JSON-пейлоад на ваш ендпоінт щойно подія виявлена в нашому циклі оновлення даних. Жодних cron-задач, жодної арифметики ліміту запитів, жодних вікон застарілих даних. Цей посібник охоплює повне налаштування: отримання вебхуків, валідацію пейлоадів, маршрутизацію сповіщень до Telegram або Discord і коректну обробку збоїв.

Опитування проти push-доставки: що ви насправді втрачаєте

Ціна опитування — не лише затримка. Розглянемо математику типової інтеграції. Якщо ви опитуєте ендпоінт когортних метрик кожні п'ять хвилин, це 288 запитів на день, або приблизно 8,640 на місяць, для одного ендпоінту по одному активу. Додайте п'ять активів — і отримаєте 43,200 запитів. Додайте знімки order flow і ризик ліквідацій, і ви можете витратити весь ліміт у 50,000 запитів на місяць тарифу Pulse лише на моніторинг, не залишивши нічого для запитів за потребою.

Вебхуки повністю усувають цю проблему. Ви реєструєтеся на події, які вас цікавлять, і запити надходять лише тоді, коли щось справді змінюється. Спокійний ринок не коштує вам нічого. Волатильний день породжує сплеск пейлоадів, але кожен з них несе дієву інформацію, а не відповідь "нічого не змінилося", яку потрібно обробити й відкинути.

Різниця в затримці теж важлива. При п'ятихвилинному опитуванні максимальна затримка виявлення складає трохи менше п'яти хвилин, і ви несете весь overhead від запитів навіть коли нічого не змінюється. З вебхуками ви отримуєте пейлоад у той момент, коли наша система виявляє подію в своєму циклі оновлення, без жодних даремних викликів між ними. Для зсувів когорт і стрибків ліквідацій усунення overhead опитування і миттєва push-доставка означають чистішу архітектуру і швидші петлі реакції.

Налаштування вашого вебхук-ендпоінту

Приймач — це просто HTTP-сервер, який приймає POST-запити, валідує пейлоад і швидко повертає статус 200. Ваш ендпоінт повинен відповідати протягом кількох секунд, щоб не активувати логіку повторних спроб. Якщо доставка не вдається, вона повторюється з експоненційним відступом. Постійні збої призведуть до призупинення вебхука, доки ви не ввімкнете його знову з дашборду.

Ось мінімальний Node.js-приймач на Express:

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.HT_WEBHOOK_SECRET;

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

app.post('/webhooks/hypertracker', (req, res) => {
  const signature = req.headers['x-ht-signature'];

  if (!signature || !verifySignature(req.body, signature)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Acknowledge immediately, process async
  res.status(200).json({ received: true });

  // Handle the event
  processEvent(req.body);
});

app.listen(3000, () => console.log('Webhook receiver on :3000'));

Три речі, на які варто звернути увагу. По-перше, перевірка підпису не є опціональною. Без неї будь-хто, хто дізнається URL вашого ендпоінту, може надсилати підроблені пейлоади. Перевірка HMAC-SHA256 підтверджує, що пейлоад надійшов від HyperTracker. По-друге, підтверджуйте до обробки. Надішліть 200 одразу, а потім асинхронно обробляйте бізнес-логіку. Якщо ваша маршрутизація сповіщень звертається до повільного downstream-сервісу (збій Telegram API, запис до бази даних), ви не хочете, щоб через це закінчився таймаут доставки вебхука і спрацювала повторна спроба. По-третє, використовуйте timingSafeEqual для порівняння, щоб запобігти timing-атакам на підпис.

Відкриття доступу до локального сервера

Під час розробки ваш localhost недоступний з інтернету. Використовуйте тунель, щоб відкрити до нього доступ:

# Option 1: ngrok
ngrok http 3000

# Option 2: Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

Скопіюйте згенерований HTTPS URL і вставте його в конфігурацію вебхука HyperTracker. У продакшні розгорніть на будь-якому хмарному провайдері, який дає вам стабільний HTTPS-ендпоінт. VPS за $5/міс цілком достатньо для приймача вебхуків.

Вибір подій для підписки

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

Практична початкова конфігурація для трейдера, що моніторить Hyperliquid:

| Тип події | Коли спрацьовує | Чому важливо | | --- | --- | --- | | cohort.shift | PnL-когорта перевертається в нетто-лонг/шорт по активу | Розвороти Money Printer або Smart Money — сигнали з високою впевненістю | | liquidation.cluster | Показник ризику ліквідацій перевищує поріг | Кластерні зони притягують ціну, особливо у волатильні сесії | | position.large | Позиція вище порогу за номіналом відкривається або закривається | Входи і виходи Whale рухають ринки на Hyperliquid | | order_flow.spike | Обсяг order flow у 5-хвилинному вікні перетинає поріг z-score | Раптові сплески потоку часто передують спрямованим рухам |

Ви налаштовуєте ці події в дашборді HyperTracker у розділі Settings > Webhooks, або програмно через ендпоінти управління вебхуками. Кожен тип події приймає необов'язкові фільтри: символ активу, ID когорти, мінімальний номінальний розмір і порогові значення. Фільтрація на джерелі завжди краща, ніж фільтрація у вашому приймачі, бо вона зменшує обсяг пейлоадів і тримає логіку обробки чистою.

Маршрутизація сповіщень до Telegram

Telegram є стандартним каналом сповіщень для криптотрейдерів, бо він швидкий, підтримує розширене форматування і працює на всіх пристроях. Функція маршрутизації бере валідований вебхук-пейлоад і надсилає відформатоване повідомлення у ваш Telegram-чат або групу.

async function sendTelegramAlert(event) {
  const TELEGRAM_TOKEN = process.env.TELEGRAM_BOT_TOKEN;
  const CHAT_ID = process.env.TELEGRAM_CHAT_ID;

  const message = formatMessage(event);

  await fetch(
    `https://api.telegram.org/bot${TELEGRAM_TOKEN}/sendMessage`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: CHAT_ID,
        text: message,
        parse_mode: 'HTML',
      }),
    }
  );
}

function formatMessage(event) {
  switch (event.type) {
    case 'cohort.shift':
      return [
        `<b>Cohort Shift: ${event.data.asset}</b>`,
        `${event.data.cohort_name} flipped <b>${event.data.direction}</b>`,
        `Net position: ${event.data.net_position.toFixed(2)}`,
        `Time: ${new Date(event.timestamp).toUTCString()}`,
      ].join('\n');

    case 'liquidation.cluster':
      return [
        `<b>Liquidation Cluster: ${event.data.asset}</b>`,
        `Risk score: ${event.data.risk_score}/100`,
        `Price zone: $${event.data.price_low} - $${event.data.price_high}`,
        `Estimated exposure: $${(event.data.notional / 1e6).toFixed(1)}M`,
      ].join('\n');

    default:
      return `<b>${event.type}</b>\n${JSON.stringify(event.data, null, 2)}`;
  }
}

Щоб створити свого Telegram-бота, напишіть @BotFather у Telegram, виконайте /newbot і збережіть токен. Додайте бота до вашого каналу або групи сповіщень, потім отримайте chat ID з ендпоінту getUpdates. Весь процес займає близько двох хвилин.

Альтернатива з Discord

Якщо ваша команда працює в Discord, доставка вебхуків ще простіша. Discord-канали мають вбудовані webhook URL. Управління токенами бота не потрібне:

async function sendDiscordAlert(event) {
  const DISCORD_WEBHOOK_URL = process.env.DISCORD_WEBHOOK_URL;

  await fetch(DISCORD_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      embeds: [{
        title: `${event.type}: ${event.data.asset}`,
        description: formatMessage(event),
        color: event.data.direction === 'long' ? 0x22c55e : 0xef4444,
        timestamp: event.timestamp,
      }],
    }),
  });
}

Маршрутизатор processEvent

Коли приймач і канали доставки налаштовані, маршрутизатор зв'язує їх разом. Тут ви вирішуєте, які події куди йдуть, застосовуєте локальну фільтрацію і додаєте збереження для налагодження.

async function processEvent(event) {
  // Log every event for debugging and replay
  console.log(JSON.stringify({ ts: Date.now(), event }));

  // Route by event type and severity
  switch (event.type) {
    case 'cohort.shift':
      // Only alert on the high-conviction cohorts
      const alertCohorts = [
        'Money Printer', 'Smart Money', 'Leviathan', 'Tidal Whale'
      ];
      if (alertCohorts.includes(event.data.cohort_name)) {
        await sendTelegramAlert(event);
        await sendDiscordAlert(event);
      }
      break;

    case 'liquidation.cluster':
      // Adjust threshold to your risk tolerance
      if (event.data.risk_score > 75) {
        await sendTelegramAlert(event);
      }
      break;

    case 'position.large':
      await sendTelegramAlert(event);
      break;

    case 'order_flow.spike':
      // Example: z > 3 catches extreme spikes. Tune for your strategy.
      if (event.data.z_score > 3) {
        await sendTelegramAlert(event);
      }
      break;

    default:
      console.log('Unhandled event type:', event.type);
  }
}

Зверніть увагу на шар фільтрації. Обробник cohort.shift надсилає сповіщення лише для Money Printer, Smart Money, Leviathan і Tidal Whale. Це когорти, де спрямовані зсуви несуть найбільший сигнал: гаманці з $1M+ сукупного прибутку (Money Printer), від $100K до $1M (Smart Money) і найбільші розміри рахунків (від $1M до $5M для Tidal Whale, $5M+ для Leviathan). Зсув від когорт Shrimp або Fish не є беззмістовним, але він генерує надто багато шуму для каналу сповіщень, якому потрібно довіряти.

Обробка збоїв без втрати подій

Розподілені системи дають збої. Ваш сервер падає під час деплою. Telegram обмежує вас у волатильну годину. Discord повертає 502 протягом тридцяти секунд. Якщо ваш конвеєр сповіщень не обробляє ці збої, ви пропускаєте найважливіші події — ті, що спрацьовують під час хаосу.

Два паттерни, які добре поєднуються:

1. Локальна черга повторних спроб

Коли канал доставки дає збій, помістіть подію в чергу повторних спроб замість того, щоб відкинути її. Простий масив у пам'яті підходить для малообсягових налаштувань. Для продакшну використовуйте Redis або надійну чергу:

const retryQueue = [];

async function safeDeliver(deliverFn, event, channel) {
  try {
    await deliverFn(event);
  } catch (err) {
    console.error(`Delivery failed (${channel}):`, err.message);
    retryQueue.push({ deliverFn, event, channel, attempts: 1 });
  }
}

// Process retries every 30 seconds
setInterval(async () => {
  const batch = retryQueue.splice(0, 10);
  for (const item of batch) {
    try {
      await item.deliverFn(item.event);
    } catch {
      item.attempts++;
      if (item.attempts < 5) retryQueue.push(item);
      else console.error('Dropped after 5 retries:', item.event.type);
    }
  }
}, 30_000);

2. Журнал подій для відтворення

Логуйте кожен вхідний вебхук у файл або базу даних до маршрутизації. Якщо ви виявите помилку в логіці форматування або пропустите канал доставки, ви зможете відтворити журнал для відновлення сповіщень. Рядок JSON-логування у processEvent вище — найпростіша версія цього підходу. Для продакшну дописуйте у файл або записуйте до таблиці SQLite.

Тестування вашого конвеєра вебхуків

Перш ніж покладатися на реальні ринкові події, перевірте свій конвеєр наскрізно із синтетичними пейлоадами. Надішліть тестовий POST на ваш локальний ендпоінт із реалістичною формою пейлоада:

curl -X POST http://localhost:3000/webhooks/hypertracker \
  -H "Content-Type: application/json" \
  -H "x-ht-signature: test-skip-in-dev" \
  -d '{
    "event_id": "test-001",
    "type": "cohort.shift",
    "timestamp": "2026-07-10T14:30:00Z",
    "data": {
      "asset": "ETH",
      "cohort_name": "Money Printer",
      "cohort_id": 8,
      "direction": "short",
      "net_position": -1247.5
    }
  }'

Перевірте, що ваш Telegram-канал або Discord-сервер отримує відформатоване сповіщення. Потім протестуйте шлях збою: тимчасово відключіть токен вашого Telegram-бота, надішліть ще одну тестову подію і переконайтеся, що вона потрапила до черги повторних спроб. Ці дві перевірки, щасливий шлях і шлях збою, виявляють більшість проблем інтеграції до виходу в продакшн.

Дашборд HyperTracker також має кнопку "Send test event" на сторінці конфігурації вебхука. Вона надсилає реальну форму пейлоада через продакшн-конвеєр доставки, щоб ви могли перевірити, що ваш ендпоінт доступний і відповідає коректно, не чекаючи ринкової події.

Від сповіщень до автоматизації

Коли конвеєр сповіщень запущено, наступний логічний крок — програмно реагувати на ці сигнали. Та сама функція processEvent, що маршрутизує до Telegram, може також запускати угоди, коригувати позиції або оновлювати дашборд. Зсув когорти Money Printer у нетто-шорт по BTC може автоматично підтягнути ваші стоп-лоси. Кластер ліквідацій, що формується вище поточної ціни, може ініціювати хедж.

Архітектура масштабується, бо вебхуки розв'язують виявлення від дії. Ваш приймач обробляє шар "щось сталося". Окремі модулі обробляють шар "що нам з цим робити". Ви можете додати нову дію (постити в Slack, логувати до бази даних, запускати сповіщення в TradingView) не зачіпаючи приймач або валідацію підпису.

HyperTracker класифікує кожен гаманець на Hyperliquid у 16 поведінкових когорт: вісім за розміром рахунку (від Shrimp до Leviathan) і вісім за загальним PnL (від Money Printer до Giga-Rekt). Коли ці класифікації зміщуються в сукупності, вебхук спрацьовує. Ваша задача — вирішити, що цей зсув означає для ваших позицій і налаштувати відповідну реакцію.

Почніть будувати з вебхуками

Доставка вебхуків доступна на тарифах HyperTracker Flow ($799/міс) і Stream ($1,999/міс). Flow дає вам вебхуки плюс 400,000 API-запитів на місяць і ліміт 200 запитів/хвилину. Stream додає WebSocket-доставку, 2 мільйони запитів на місяць і 500 запитів/хвилину. Обидва включають повну аналітику когорт, order flow та ендпоінти ризику ліквідацій, які живлять події сповіщень, показані в цьому посібнику.

Вивчіть тарифи HyperTracker API

Більшість торгової інфраструктури починається з циклу опитування, бо саме це показують туторіали. Розробники, які будують системи продакшн-рівня, переходять на push-доставку якомога раніше, бо кожна хвилина затримки у виявленні сигналу накопичується в пропущені угоди і застарілі сповіщення. Тридцять хвилин налаштування зараз позбавлять вас від налагодження нестабільного cron-завдання о третій ночі, коли ринок рухається.