Ваш торговий бот не повинен використовувати polling: Webhooks для сповіщень Hyperliquid

Кожні п'ять секунд ваш бот пінгує сервер. "Щось нове?" Ні. "Щось нове?" Ні. "Щось нове?" Все ще ні. А потім когорта whale перевертається в net long на BTC, рух, який вам потрібно було зловити миттєво, але наступний запланований poll буде ще через чотири секунди. Цей розрив коштує вам входу.

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

Цим дзвінком є webhook. І якщо ви будуєте щось, що реагує на ринкові умови на Hyperliquid, розуміння того, коли використовувати webhooks (а коли polling насправді є кращим вибором), заощадить вам зайві API-виклики, спростить код і прискорить час реакції.

Податок на polling: чому ваш бот витрачає ліміт запитів даремно

REST polling є стандартною архітектурою для більшості торгових ботів, і на це є вагомі причини. Це просто. Ви пишете цикл, викликаєте GET /cohort-metrics кожні N секунд, порівнюєте відповідь із попередньою і діяте, коли щось змінюється. Десять рядків коду, ніякої інфраструктури, крім самого бота.

Але простота має приховану ціну. Якщо ви робите polling кожні 60 секунд по трьох ендпоінтах (позиції когорт, ризик ліквідації та ставки фінансування), це 4 320 API-запитів на день. На плані Pulse з 50 000 запитів на місяць ви витратите весь ліміт приблизно за 11 днів лише на polling, не залишивши нічого для разових запитів або історичного аналізу.

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

Webhooks перевертають модель

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

Для аналітики Hyperliquid події, для яких ви б налаштували webhooks, це ті, що насправді впливають на торгові рішення:

• Зсуви позиціонування когорт: Smart Money (гаманці з усіма часами PnL від +$100K до +$1M) переходить з net short на net long по ETH
• Порогові значення ризику ліквідації: рівень ліквідаційної експозиції на рівні активу перетинає налаштований ступінь серйозності
• Екстремальні ставки фінансування: ставки стрибають вище порогу, який ви задаєте, сигналізуючи про перекуплене позиціонування
• Великі зміни позицій: когорти Whale або Leviathan відкривають або закривають значні позиції

Кожна з цих подій рідкісна. Вони не відбуваються щосекунди і навіть щохвилини. Саме тому polling для них є марнотратним, а webhooks є природним рішенням. Ваш бот простоює (витрачаючи нуль API-викликів) аж до того моменту, коли спрацьовує налаштована умова. Тоді він отримує POST, валідує корисне навантаження та виконує свою логіку.

Як насправді працює потік сповіщень через webhook

Архітектура є зрозумілою, але деталі мають значення. Ось послідовність від ринкової події до дії бота:

1. Відбувається ринкова подія. Гаманці когорти Whale (з перп-капіталом від $500K до $1M) колективно змінюють своє позиціонування по BTC з net short на net long.
2. HyperTracker виявляє зсув. Наш конвеєр даних обробляє зміну стану когорти під час наступного циклу оновлення та оцінює її відповідно до налаштованих вами правил webhook.
3. Webhook спрацьовує. POST-запит надходить на ваш зареєстрований ендпоінт із JSON-корисним навантаженням, що містить тип події, актив, когорту, напрямок і величину.
4. Ваш обробник валідує і діє. Він перевіряє підпис HMAC, розбирає корисне навантаження та виконує будь-яку логіку, яку ви побудували: відкриває позицію, оновлює дашборд, надсилає сповіщення в Telegram або все разом.

Що повинен робити ваш обробник

Отримати webhook — це легка частина. Надійно його обробити — тут більшість розробників спотикається. Ваш ендпоінт повинен:

• Валідувати підпис. Кожен webhook повинен містити заголовок із підписом HMAC. Перевіряйте його відповідно до вашого спільного секрету перед обробкою корисного навантаження. Якщо пропустити цей крок, будь-хто, хто дізнається URL вашого ендпоінта, зможе надсилати фальшиві події.
• Відповідати швидко. Повертайте статус 200 протягом кількох секунд. Якщо вашому обробнику потрібно виконати дорогу роботу (розмістити угоду, запустити модель), спочатку підтвердіть webhook, а потім обробляйте асинхронно за допомогою черги завдань.
• Обробляти дублікати. Мережеві проблеми можуть призвести до повторних спроб. Включіть логіку ідемпотентності, щоб одна й та сама подія не запустила вашого бота двічі. Простий підхід: хешуйте корисне навантаження, перевіряйте за короткостроковим кешем, пропускайте, якщо вже бачили.
• Логувати все. Корисні навантаження webhook ефемерні. Після їх обробки вони зникають, якщо ви їх не зберігаєте. Логуйте кожну вхідну подію з міткою часу для відлагодження та бектестингу.

# Мінімальний обробник webhook (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"}

Коли polling все ж є правильним вибором

Webhooks не є універсально кращими за polling. Вони вирішують конкретну проблему (реагування на рідкісні події без марної трати запитів), але існують сценарії, де polling є чистішою архітектурою:

Регулярне оновлення дашборду. Якщо ви будуєте аналітичний дашборд, що показує позиціонування когорт по всіх активах кожні кілька хвилин, запланований poll є простішим рішенням, ніж керування десятками webhook-підписок. Вам потрібен повний знімок через регулярні інтервали, і саме для цього призначений REST.

Запити до історичних даних. Webhooks орієнтовані на майбутнє. Вони повідомляють, коли щось станеться надалі. Якщо вам потрібні історичні дані когорт для бектестингу (HyperTracker зберігає до чотирьох тижнів метрик когорт по монетах і понад шість місяців даних по позиціях і угодах), це REST-запит.

Прості боти на старших тарифах. Якщо ви на тарифі Flow або Stream із сотнями тисяч запитів на місяць, вартість "зайвого poll" є незначною. Бот, що робить polling одного ендпоінта кожні п'ять хвилин, використовує приблизно 8 640 запитів на місяць, добре вкладаючись у ваш бюджет. Архітектурна складність webhooks може просто не окупитися.

Емпіричне правило: використовуйте webhooks, коли ваш бот чекає на конкретні умови і діє за тригерами. Використовуйте polling, коли вашому боту потрібні регулярні знімки загального стану ринку. Багато виробничих систем використовують обидва: webhooks для сповіщень, REST для завантаження контексту, коли сповіщення спрацювало.

Вибір методу доставки на HyperTracker

HyperTracker пропонує три методи доставки в різних цінових тарифах, і правильний вибір залежить від того, що ви будуєте і наскільки подієво-орієнтована ваша архітектура.

REST (всі тарифи). Кожен тариф від Free до Stream включає REST-доступ. Для розробників-початківців REST polling є найшвидшим способом прототипування та валідації торгової стратегії перед інвестуванням у push-інфраструктуру.

Webhooks (Flow і Stream). Доступно починаючи з тарифу Flow ($799/міс, 400K запитів/міс, ліміт 200 запитів/хв). Це оптимальний варіант для ботів на основі сповіщень. Ви налаштовуєте, які події відстежувати, реєструєте свій ендпоінт і дозволяєте серверу виконувати моніторинг. Ваш бюджет ліміту запитів залишається вільним для запитів за вимогою.

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

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

Найнадійніші виробничі налаштування поєднують методи доставки. Типова схема для торгового бота Hyperliquid на тарифі Flow:

1. Webhooks відстежують зсуви позиціонування когорт і перетин порогових значень ризику ліквідації. Коли вони спрацьовують, бот прокидається.
2. REST-виклики завантажують контекст, коли webhook спрацьовує. Бот запитує поточні позиції, останні угоди та ширші ринкові метрики для прийняття обґрунтованого рішення.
3. REST polling виконується з повільним розкладом (кожні 15 хвилин) для підтримки локального кешу загального стану ринку. Цей кеш прискорює рішення, що спрацьовують через webhook, оскільки контекст вже завантажено.

Ця гібридна модель забезпечує ефективне використання ліміту запитів: повільний poll використовує мінімум запитів, webhook коштує нуль запитів (сервер надсилає вам сам), а спалах REST-викликів після спрацювання сповіщення є цільовим і коротким.

Поширені пастки webhook (і як їх уникнути)

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

Якщо ваш сервер недосяжний у момент спрацювання webhook, ви пропускаєте подію. На відміну від polling (де ви просто спробуєте ще раз у наступному циклі), пропущений webhook зникає, якщо провайдер не повторює спробу. Забезпечте надлишковість: запускайте ваш обробник у хмарного провайдера з гарантіями доступності та реалізуйте чергу неуспішних доставок, щоб потім їх відтворити.

Ігнорування валідації підпису

Відкритий URL webhook без валідації підпису — це відчинені двері. Будь-хто може надіслати фальшиві події на ваш ендпоінт і запустити вашого бота. Завжди перевіряйте підпис HMAC відповідно до вашого спільного секрету перед тим, як діяти відповідно до корисного навантаження. Це обов'язково для будь-якого бота, що торгує реальним капіталом.

Блокування обробника

Якщо ваш webhook-обробник відповідає 30 секунд, тому що синхронно розміщує угоду, система доставки може перевищити час очікування і повторити спробу, що може призвести до дублювання дії. Негайно підтверджуйте webhook (поверніть 200), а потім обробляйте асинхронно. Черги завдань на кшталт BullMQ, Celery або навіть простий Redis-список вирішують це чисто.

Відсутність моніторингу

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

Будуйте подієво-орієнтовані сповіщення на даних Hyperliquid

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

Переглянути тарифи HyperTracker

Підводимо підсумок: система прийняття рішень

Якщо ви будуєте на Hyperliquid і вибираєте між polling і webhooks, відповідь майже завжди "обидва, для різних речей." Але ось коротка система для закріплення рішення щодо кожного потоку даних, який споживає ваш бот:

| Питання | Якщо так | | --- | --- | | Чи реагує бот на конкретні події (зсув когорти, стрибок ризику ліквідації)? | Webhook | | Чи потрібні боту регулярні повні знімки ринку? | REST poll з повільним інтервалом | | Чи потрібні боту історичні дані для бектестингу? | REST-запит (одноразовий або пакетний) | | Чи відстежує бот багато активів паралельно та безперервно? | WebSocket (якщо на тарифі Stream) | | Чи є бот прототипом або MVP? | Почніть з REST polling, пізніше переходьте на webhooks |

Розробники, що отримують максимум від наших даних, використовують webhooks, щоб знати, коли дивитися, і REST, щоб розуміти, на що вони дивляться. Webhook повідомляє їм "Smart Money щойно перейшов у long по ETH." REST-виклик розповідає, наскільки великим є зсув, що роблять інші когорти і чи підтримує ризик ліквідації цей рух.

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