Создание системы webhook-уведомлений для Hyperliquid за 30 минут

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

Опрос — подход по умолчанию, потому что это простейшая схема. Вы задаёте интервал, обращаетесь к эндпоинту, сравниваете ответ и считаете задачу выполненной. Но за простоту приходится платить: задержкой, лишними API-запросами к неизменившимся данным и постоянным ощущением, что что-то важное произошло между двумя последними запросами. Webhooks переворачивают эту модель. Вместо того чтобы каждые несколько минут спрашивать «что-то изменилось?», сервер сам сообщает вам, как только что-то происходит.

Доставка webhook доступна в тарифах HyperTracker Flow ($799/мес.) и Stream ($1,999/мес.). Вы регистрируете URL, настраиваете интересующие вас события, и наша инфраструктура отправляет подписанный JSON-payload на ваш эндпоинт сразу после обнаружения события в цикле обновления данных. Никаких cron-задач, никакой арифметики с rate limit, никаких устаревших окон данных. В этом руководстве описан полный процесс настройки: приём webhook, валидация payload, маршрутизация уведомлений в Telegram или Discord и корректная обработка сбоев.

Опрос против push: что вы теряете на самом деле

Цена опроса — не только задержка. Посчитайте математику для типичной интеграции. Если вы опрашиваете эндпоинт метрик когорт каждые пять минут, это 288 запросов в день, или около 8 640 в месяц, для одного эндпоинта по одному активу. Добавьте пять активов — получите 43 200 запросов. Добавьте снимки order flow и риска ликвидации, и вы сожжёте весь лимит тарифа Pulse в 50 000 запросов в месяц только на мониторинг, не оставив ничего для запросов по требованию.

Webhooks полностью устраняют эту проблему. Вы подписываетесь на интересующие вас события, и запросы отправляются только тогда, когда что-то реально меняется. Спокойный рынок не стоит вам ничего. Волатильный день посылает burst payload-ов, но каждый из них несёт полезную информацию, а не ответ «изменений нет», который нужно обработать и выбросить.

Разница в задержке тоже важна. При пятиминутном опросе максимальная задержка обнаружения составляет почти пять минут, и вы несёте все накладные расходы на запросы, даже когда ничего не меняется. С webhook вы получаете payload в момент, когда система обнаруживает событие в своём цикле обновления, без единого лишнего запроса. Для сдвигов когорт и всплесков ликвидаций устранение накладных расходов опроса и мгновенная push-доставка означают более чистую архитектуру и более быстрые петли реакции.

Настройка webhook-эндпоинта

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

Вот минимальный получатель на 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 вашего эндпоинта, сможет отправлять поддельные payload-ы. Проверка HMAC-SHA256 подтверждает, что payload поступил от HyperTracker. Второе: подтверждайте получение до обработки. Отправьте 200 немедленно, а затем обрабатывайте бизнес-логику асинхронно. Если маршрутизация уведомлений упирается в медленный downstream-сервис (сбой Telegram API, запись в базу данных), вы не хотите, чтобы доставка webhook истекла по таймауту и запустила повторную попытку. Третье: используйте timingSafeEqual для сравнения, чтобы предотвратить атаки по времени на подпись.

Открытие локального сервера для внешних запросов

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

# Option 1: ngrok
ngrok http 3000

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

Скопируйте сгенерированный HTTPS-адрес и вставьте его в настройки webhook HyperTracker. В продакшене разворачивайте на любом облачном провайдере, дающем стабильный HTTPS-эндпоинт. VPS за $5 в месяц вполне достаточно для webhook-получателя.

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

Не каждое событие заслуживает уведомления. Самый быстрый способ испортить канал уведомлений — засыпать его шумом, пока вы не начнёте игнорировать всё подряд. Начните с компактного набора высокосигнальных событий, а затем расширяйте его, когда почувствуете объём.

Практическая стартовая конфигурация для трейдера, отслеживающего 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 или программно через эндпоинты управления webhook. Каждый тип события принимает необязательные фильтры: символ актива, ID когорты, минимальный номинальный размер и пороговые значения. Фильтрация на источнике всегда лучше, чем в получателе: она снижает объём payload-ов и сохраняет логику обработки чистой.

Маршрутизация уведомлений в Telegram

Telegram — стандартный канал уведомлений для крипто-трейдеров: он быстрый, поддерживает богатое форматирование и работает на любом устройстве. Функция маршрутизации принимает проверенный webhook-payload и отправляет отформатированное сообщение в ваш 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, доставка webhook ещё проще. Каналы 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 на тридцать секунд. Если ваш pipeline уведомлений не обрабатывает эти сбои, вы пропускаете именно те события, которые важнее всего: те, что срабатывают во время хаоса.

Два паттерна, которые хорошо работают вместе:

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. Журнал событий для воспроизведения

Записывайте каждый входящий webhook в файл или базу данных до его маршрутизации. Если вы обнаружите ошибку в логике форматирования или пропустите канал доставки, можно воспроизвести журнал для восстановления уведомлений. Строка JSON-логирования в processEvent выше — простейший вариант этого подхода. Для продакшена дописывайте в файл или записывайте в таблицу SQLite.

Тестирование pipeline webhook

Прежде чем полагаться на реальные рыночные события, проверьте pipeline от начала до конца на синтетических payload-ах. Отправьте тестовый POST на ваш локальный эндпоинт с реалистичной структурой payload:

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» на странице настройки webhook. Она отправляет реальную структуру payload через production-pipeline доставки, так что вы можете проверить доступность эндпоинта и корректность ответа, не дожидаясь рыночного события.

От уведомлений к автоматизации

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

Архитектура масштабируется, потому что webhook-и разделяют обнаружение и действие. Ваш получатель обрабатывает слой «что-то произошло». Отдельные модули обрабатывают слой «что мы с этим делаем». Вы можете добавить новое действие (отправить в Slack, записать в базу данных, запустить алерт TradingView) без изменения получателя или валидации подписи.

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

Начните строить с webhook-ами

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

Explore HyperTracker API tiers

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