Ваш торговый бот не должен опрашивать сервер: вебхуки для Hyperliquid-алертов

Каждые пять секунд бот пинает сервер. "Есть что-то новое?" Нет. "Есть что-то новое?" Нет. "Есть что-то новое?" Всё ещё нет. А потом когорта Whale переходит в чистый лонг по BTC — движение, которое нужно было поймать немедленно, но следующий плановый опрос через четыре секунды. Этот разрыв стоит вам точки входа.

В этом и есть фундаментальная проблема REST-опроса для торговых алертов. Это работает, но работает как проверка почтового ящика каждые две минуты вместо того, чтобы дождаться звонка в дверь. Для аналитических дашбордов и исторических запросов опрос вполне подходит. Для событийной торговли на Hyperliquid, где когортные сдвиги и кластеры ликвидаций способны переформировать рынок за минуты, нужен именно звонок в дверь.

Этот звонок — вебхук. И если вы строите что-либо, реагирующее на рыночные условия на Hyperliquid, понимание того, когда использовать вебхуки (а когда опрос на самом деле лучший выбор), сэкономит вам API-вызовы, упростит код и ускорит реакцию.

Цена опроса: почему ваш бот сжигает лимит запросов впустую

REST-опрос — стандартная архитектура для большинства торговых ботов, и не без причины. Это просто. Пишете цикл, вызываете GET /cohort-metrics каждые N секунд, сравниваете ответ с предыдущим и действуете, когда что-то меняется. Десять строк кода, никакой инфраструктуры помимо самого бота.

Но простота несёт скрытые издержки. Если вы опрашиваете три эндпоинта каждые 60 секунд (позиционирование когорт, риск ликвидации и ставки финансирования) — это 4 320 API-запросов в день. На плане Pulse с 50 000 запросов в месяц вы израсходуете весь лимит примерно за 11 дней только на опрос, не оставив ничего для разовых запросов или исторического анализа.

Настоящая проблема — расточительство. Большинство из этих 4 320 ежедневных запросов возвращают идентичные данные. Позиционирование когорт не меняется каждую минуту. Пороги риска ликвидации не срабатывают постоянно. Вы платите (лимитом запросов и нагрузкой на сервер) за многократное подтверждение того, что ничего не произошло.

Вебхуки переворачивают модель

Вебхук инвертирует отношения между вашим ботом и источником данных. Вместо того чтобы бот по таймеру спрашивал "что-то изменилось?", вы передаёте серверу URL — ваш эндпоинт — и говорите: "Отправьте POST на этот адрес, когда произойдёт то, что меня интересует." Сервер ведёт наблюдение. Бот реагирует.

Для аналитики Hyperliquid события, под которые стоит настроить вебхуки, — это именно те, что действительно влияют на торговые решения:

• Сдвиги позиционирования когорт: Smart Money (кошельки с совокупным PnL от +$100K до +$1M) переходит из чистого шорта в чистый лонг по ETH
• Пороги риска ликвидации: ликвидационная экспозиция на уровне актива пересекает заданный порог серьёзности
• Экстремальные ставки финансирования: ставки выходят за порог, который вы определяете, сигнализируя о перегруженности позиций
• Крупные изменения позиций: когорты Whale или Leviathan открывают или закрывают значительные позиции

Каждое из этих событий редкое. Они случаются не каждую секунду и даже не каждую минуту. Именно поэтому опрос расточителен для них, а вебхуки — естественный выбор. Бот простаивает (потребляя ноль API-вызовов) до того момента, когда срабатывает настроенное условие. Тогда он получает POST, валидирует payload и выполняет свою логику.

Как на самом деле работает алерт через вебхук

Архитектура проста, но детали важны. Вот последовательность от рыночного события до действия бота:

1. Рыночное событие. Кошельки когорты Whale (с перп-капиталом от $500K до $1M) совокупно смещают своё BTC-позиционирование из чистого шорта в чистый лонг.
2. HyperTracker фиксирует сдвиг. Наш конвейер данных обрабатывает изменение состояния когорты в следующем цикле обновления и сверяет его с вашими настроенными правилами вебхука.
3. Вебхук срабатывает. POST-запрос поступает на ваш зарегистрированный эндпоинт с JSON-payload, содержащим тип события, актив, когорту, направление и величину.
4. Ваш обработчик валидирует и действует. Он проверяет HMAC-подпись, разбирает payload и выполняет логику, которую вы написали: открыть позицию, обновить дашборд, отправить Telegram-алерт или всё вместе.

Что должен делать ваш обработчик

Принять вебхук легко. Надёжно его обработать — вот где большинство разработчиков спотыкается. Ваш эндпоинт должен:

• Валидировать подпись. Каждый вебхук должен содержать заголовок с HMAC-подписью. Проверяйте её по общему секрету до обработки payload. Пропустить этот шаг — значит открыть дверь для любого, кто узнает URL вашего эндпоинта и сможет отправлять поддельные события.
• Отвечать быстро. Возвращайте статус 200 в течение нескольких секунд. Если обработчику нужно выполнить ресурсоёмкую работу (разместить сделку, запустить модель), сначала подтвердите получение вебхука, затем обрабатывайте асинхронно через очередь задач.
• Обрабатывать дубликаты. Из-за сетевых проблем возможны повторные попытки доставки. Реализуйте идемпотентность, чтобы одно событие не запускало бота дважды. Простой подход: хешируйте payload, проверяйте по кратковременному кэшу, пропускайте, если уже видели.
• Логировать всё. Payload вебхука эфемерен. После обработки он исчезнет, если вы его не сохраните. Логируйте каждое входящее событие с меткой времени для отладки и бэктестинга.

# Минимальный обработчик вебхука (Python / FastAPI)
from fastapi import FastAPI, Request, HTTPException
import hmac, hashlib

app = FastAPI()
WEBHOOK_SECRET = "your_shared_secret"

@app.post("/webhook/alerts")
async def handle_alert(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Signature")

    expected = hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature or "", expected):
        raise HTTPException(status_code=401)

    payload = await request.json()
    # Enqueue for async processing
    process_alert.delay(payload)
    return {"status": "received"}

Когда опрос всё же является правильным выбором

Вебхуки не лучше опроса в любой ситуации. Они решают конкретную задачу (реагировать на редкие события, не расходуя запросы впустую), но есть сценарии, где опрос — более чистая архитектура:

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

Исторические запросы данных. Вебхуки направлены в будущее. Они сообщают о том, что произойдёт с этого момента. Если вам нужны исторические данные когорт для бэктестинга (HyperTracker хранит до четырёх недель детальных метрик когорт по монетам и более шести месяцев данных о позициях и сделках) — это REST-запрос.

Простые боты на тарифах с большим лимитом. Если вы на плане Flow или Stream с сотнями тысяч запросов в месяц, "потерянная" стоимость опроса пренебрежимо мала. Бот, опрашивающий один эндпоинт каждые пять минут, использует около 8 640 запросов в месяц — хорошо в рамках лимита. Архитектурная сложность вебхуков может не стоить усилий.

Практическое правило: используйте вебхуки, когда бот ждёт конкретных условий и действует по триггерам. Используйте опрос, когда боту нужны периодические снимки общего состояния рынка. Многие production-системы используют оба подхода: вебхуки для алертов, REST для загрузки контекста при срабатывании алерта.

Выбор метода доставки в HyperTracker

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

REST (все планы). Каждый тариф от Free до Stream включает REST-доступ. Для разработчиков, только начинающих, REST-опрос — самый быстрый способ прототипировать и проверять торговую стратегию до инвестиций в push-инфраструктуру.

Вебхуки (Flow и Stream). Доступны начиная с тарифа Flow ($799/мес, 400K запросов в месяц, лимит 200 запросов в минуту). Это оптимальный вариант для алерт-ориентированных ботов. Вы настраиваете, за какими событиями следить, регистрируете эндпоинт и даёте серверу вести мониторинг. Лимит запросов остаётся свободным для оперативных запросов.

WebSocket (только Stream). Тариф Stream ($1,999/мес) добавляет постоянные WebSocket-соединения для непрерывных потоков данных. Он рассчитан на институциональные конвейеры данных, дашборды мониторинга множества активов и сценарии, где нужен непрерывный поток обновлений по многим инструментам одновременно.

Гибридная архитектура

Самые надёжные production-решения комбинируют методы доставки. Типичная схема для торгового бота на Hyperliquid с планом Flow:

1. Вебхуки отслеживают сдвиги позиционирования когорт и пересечение порогов риска ликвидации. При срабатывании бот просыпается.
2. REST-вызовы загружают контекст, когда срабатывает вебхук. Бот запрашивает текущие позиции, недавние сделки и широкие рыночные метрики для взвешенного решения.
3. REST-опрос работает по медленному расписанию (каждые 15 минут) для поддержания локального кэша общего состояния рынка. Этот кэш ускоряет решения, принимаемые по триггеру вебхука, поскольку контекст уже загружен.

Эта гибридная модель сохраняет эффективность использования лимита запросов: медленный опрос использует минимум запросов, вебхук не стоит ни одного (сервер сам отправляет данные вам), а всплеск REST-вызовов при срабатывании алерта точечный и кратковременный.

Типичные ловушки при работе с вебхуками (и как их избежать)

Ваш эндпоинт недоступен

Если ваш сервер недостижим в момент срабатывания вебхука, вы пропускаете событие. В отличие от опроса (где вы просто попробуете снова в следующем цикле), пропущенный вебхук исчезает, если провайдер не реализует повторные попытки. Закладывайте избыточность: запускайте обработчик на облачном провайдере с гарантией аптайма и реализуйте очередь недоставленных сообщений для неуспешных доставок, которые можно воспроизвести позднее.

Игнорирование валидации подписи

Открытый URL вебхука без валидации подписи — это незапертая дверь. Любой может отправить поддельные события на ваш эндпоинт и запустить бота. Всегда проверяйте HMAC-подпись по общему секрету перед обработкой payload. Это обязательно для любого бота, торгующего реальным капиталом.

Блокировка обработчика

Если ваш обработчик вебхука не отвечает 30 секунд из-за синхронного размещения сделки, система доставки может превысить таймаут и повторить попытку, что потенциально приведёт к дублирующему действию. Подтверждайте получение вебхука немедленно (возвращайте 200), затем обрабатывайте асинхронно. Очереди задач — BullMQ, Celery или даже простой Redis-список — решают эту проблему чисто.

Отсутствие мониторинга

Вебхуки невидимы, когда работают, и невидимы, когда не работают. Без мониторинга вы не узнаете, если доставки молча прекратились. Настройте heartbeat: если за настраиваемое окно (например, несколько часов в активные рыночные периоды) не поступило ни одного вебхука, инициируйте внутренний алерт для расследования. Логируйте каждое входящее событие и периодически сверяйте с ожидаемой частотой доставки.

Создайте событийные алерты на данных Hyperliquid

Планы Flow и Stream HyperTracker доставляют сдвиги когорт, риски ликвидации и экстремальные ставки финансирования прямо на ваш эндпоинт. Шестнадцать поведенческих когорт, классифицированных по размеру кошелька и совокупному PnL. Один вебхук срабатывает — ваш бот реагирует.

Изучить планы HyperTracker

Подводим итог: фреймворк для принятия решений

Если вы строите на Hyperliquid и выбираете между опросом и вебхуками, ответ почти всегда "оба, для разных целей". Но вот краткий фреймворк для принятия решения по каждому потоку данных, который потребляет ваш бот:

| Вопрос | Если да | | --- | --- | | Бот реагирует на конкретные события (сдвиг когорты, всплеск риска ликвидации)? | Webhook | | Боту нужны периодические снимки всего рынка? | REST-опрос с медленным интервалом | | Боту нужны исторические данные для бэктестинга? | REST-запрос (разовый или пакетный) | | Бот мониторит множество активов одновременно в реальном времени? | WebSocket (при наличии плана Stream) | | Бот — прототип или MVP? | Начните с REST-опроса, мигрируйте на вебхуки позднее |

Разработчики, извлекающие максимум из наших данных, используют вебхуки, чтобы знать, когда смотреть, и REST, чтобы понимать, на что они смотрят. Вебхук говорит им: "Smart Money только что ушёл в лонг по ETH." REST-вызов показывает, насколько велик этот сдвиг, что делают другие когорты и подтверждает ли риск ликвидации это движение.

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