Your Trading Bot Shouldn't Poll: Webhooks for Hyperliquid Alerts

Every five seconds, your bot pings the server. "Anything new?" No. "Anything new?" No. "Anything new?" Still no. And then a whale cohort flips net long on BTC, a move you needed to catch instantly, but your next scheduled poll is four seconds away. That gap costs you the entry.

This is the fundamental problem with REST polling for trading alerts. It works, but it works like checking your mailbox every two minutes instead of having the postman ring the doorbell. For analytics dashboards and historical queries, polling is perfectly fine. For event-driven trading on Hyperliquid, where cohort shifts and liquidation clusters can reshape the market in minutes, you want the doorbell.

That doorbell is a webhook. And if you're building anything that reacts to market conditions on Hyperliquid, understanding when to use webhooks (and when polling is actually the better choice) will save you wasted API calls, simpler code, and faster reaction times.

The Polling Tax: Why Your Bot Burns Rate Limit for Nothing

REST polling is the default architecture for most trading bots, and for good reason. It's simple. You write a loop, call GET /cohort-metrics every N seconds, compare the response to the last one, and act when something changes. Ten lines of code, no infrastructure beyond the bot itself.

But simplicity comes with a hidden cost. If you're polling every 60 seconds across three endpoints (cohort positioning, liquidation risk, and funding rates), that's 4,320 API requests per day. On a Pulse plan with 50,000 requests per month, you'll burn through your entire allocation in about 11 days on polling alone, with nothing left for ad-hoc queries or historical analysis.

The real problem is waste. Most of those 4,320 daily requests return identical data. Cohort positioning doesn't change every minute. Liquidation risk thresholds don't fire constantly. You're paying (in rate limit budget and server overhead) to repeatedly confirm that nothing happened.

Webhooks Flip the Model

A webhook inverts the relationship between your bot and the data source. Instead of your bot asking "did anything change?" on a timer, you give the server a URL, your endpoint, and say "POST to this address when something I care about happens." The server does the watching. Your bot does the reacting.

For Hyperliquid analytics, the events you'd configure webhooks for are the ones that actually matter to trading decisions:

• Cohort positioning shifts: Smart Money (wallets with +$100K to +$1M all-time PnL) flipping from net short to net long on ETH
• Liquidation risk thresholds: Asset-level liquidation exposure crossing a configured severity level
• Funding rate extremes: Rates spiking beyond a threshold you define, signaling crowded positioning
• Large position changes: Whale or Leviathan cohorts opening or closing significant positions

Each of these events is sparse. They don't happen every second, or even every minute. Which is exactly why polling is wasteful for them, and webhooks are the natural fit. Your bot sits idle (consuming zero API calls) until the exact moment a configured condition fires. Then it receives a POST, validates the payload, and executes its logic.

How a Webhook Alert Flow Actually Works

The architecture is straightforward, but the details matter. Here's the sequence from market event to bot action:

1. Market event occurs. Whale-cohort wallets (those with $500K to $1M in perp equity) collectively shift their BTC positioning from net short to net long.
2. HyperTracker detects the shift. Our data pipeline processes the cohort state change during the next refresh cycle and evaluates it against your configured webhook rules.
3. Webhook fires. A POST request hits your registered endpoint with a JSON payload containing the event type, asset, cohort, direction, and magnitude.
4. Your handler validates and acts. It checks the HMAC signature, parses the payload, and executes whatever logic you've built: open a position, update a dashboard, send a Telegram alert, or all three.

What Your Handler Needs to Do

Receiving a webhook is the easy part. Handling it reliably is where most builders trip up. Your endpoint needs to:

• Validate the signature. Every webhook should include an HMAC signature header. Verify it against your shared secret before processing the payload. Skipping this step means anyone who discovers your endpoint URL can send fake events.
• Respond quickly. Return a 200 status within a few seconds. If your handler needs to do expensive work (placing a trade, running a model), acknowledge the webhook first, then process asynchronously using a job queue.
• Handle duplicates. Network issues can cause retries. Include idempotency logic so the same event doesn't trigger your bot twice. A simple approach: hash the payload, check against a short-lived cache, skip if seen before.
• Log everything. Webhook payloads are ephemeral. Once you process them, they're gone unless you store them. Log every incoming event with a timestamp for debugging and backtesting.

# Minimal webhook handler (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"}

When Polling Is Still the Right Call

Webhooks are not universally better than polling. They solve a specific problem (reacting to infrequent events without wasting requests), but there are scenarios where polling is the cleaner architecture:

Periodic dashboard refreshes. If you're building an analytics dashboard that shows cohort positioning across all assets every few minutes, a scheduled poll is simpler than managing dozens of webhook subscriptions. You want a complete snapshot at regular intervals, and that's what REST is designed for.

Historical data queries. Webhooks are forward-looking. They tell you when something happens from now on. If you need historical cohort data for backtesting (HyperTracker stores up to four weeks of per-coin cohort metrics and over six months of position and fill data), that's a REST query.

Simple bots on high-tier plans. If you're on a Flow or Stream plan with hundreds of thousands of monthly requests, the "wasted poll" cost is negligible. A bot polling one endpoint every five minutes uses roughly 8,640 requests per month, well within your budget. The architectural complexity of webhooks might not be worth it.

Rule of thumb: Use webhooks when your bot waits for specific conditions and acts on triggers. Use polling when your bot needs periodic snapshots of broad market state. Many production systems use both: webhooks for alerts, REST for context-loading when an alert fires.

Choosing Your Delivery Method on HyperTracker

HyperTracker offers three delivery methods across its pricing tiers, and the right choice depends on what you're building and how event-driven your architecture is.

REST (all plans). Every tier from Free through Stream includes REST access. For builders starting out, REST polling is the fastest way to prototype and validate a trading strategy before investing in push-based infrastructure.

Webhooks (Flow and Stream). Available starting at the Flow tier ($799/mo, 400K requests/month, 200 req/min rate limit). This is the sweet spot for alert-driven bots. You configure which events to watch, register your endpoint, and let the server handle the monitoring. Your rate limit budget stays free for on-demand queries.

WebSocket (Stream only). The Stream tier ($1,999/mo) adds persistent WebSocket connections for continuous data feeds. This is designed for institutional data pipelines, multi-asset monitoring dashboards, and scenarios where you need a constant stream of updates across many instruments simultaneously.

The Hybrid Architecture

The most robust production setups combine delivery methods. A typical pattern for a Hyperliquid trading bot on a Flow plan:

1. Webhooks watch for cohort positioning shifts and liquidation risk threshold crossings. When they fire, the bot wakes up.
2. REST calls load context when a webhook triggers. The bot queries current positions, recent fills, and broader market metrics to make an informed decision.
3. REST polling runs on a slow schedule (every 15 minutes) to maintain a local cache of general market state. This cache makes webhook-triggered decisions faster because the context is already loaded.

This hybrid model keeps your rate limit usage efficient: the slow poll uses minimal requests, the webhook costs zero requests (the server pushes to you), and the burst of REST calls when an alert fires is targeted and brief.

Common Webhook Pitfalls (and How to Avoid Them)

Your Endpoint Goes Down

If your server is unreachable when a webhook fires, you miss the event. Unlike polling (where you simply try again next cycle), a missed webhook is gone unless the provider retries. Build in redundancy: run your handler on a cloud provider with uptime guarantees, and implement a dead-letter queue for failed deliveries you can replay later.

Ignoring Signature Validation

An exposed webhook URL without signature validation is an open door. Anyone can POST fake events to your endpoint and trigger your bot. Always verify the HMAC signature against your shared secret before acting on a payload. This is non-negotiable for any bot that trades with real capital.

Blocking the Handler

If your webhook handler takes 30 seconds to respond because it's synchronously placing a trade, the delivery system may time out and retry, potentially triggering a duplicate action. Acknowledge the webhook immediately (return 200), then process asynchronously. Job queues like BullMQ, Celery, or even a simple Redis list solve this cleanly.

No Monitoring

Webhooks are invisible when they work and invisible when they don't. Without monitoring, you won't know if deliveries silently stopped. Set up a heartbeat: if no webhook fires within a configurable window (say, a few hours during active market periods), trigger an internal alert to investigate. Log every received event and periodically compare against expected delivery frequency.

Build Event-Driven Alerts on Hyperliquid Data

HyperTracker's Flow and Stream plans deliver cohort shifts, liquidation risk, and funding extremes directly to your endpoint. Sixteen behavioral cohorts, classified by wallet size and all-time PnL. One webhook fires, your bot reacts.

Explore HyperTracker Plans

Putting It Together: A Decision Framework

If you're building on Hyperliquid and deciding between polling and webhooks, the answer is almost always "both, for different things." But here's a quick framework to anchor the decision for each data feed your bot consumes:

| Question | If Yes | | --- | --- | | Does the bot react to specific events (cohort flip, liquidation risk spike)? | Webhook | | Does the bot need periodic full-market snapshots? | REST poll on a slow interval | | Does the bot need historical data for backtesting? | REST query (one-time or batch) | | Does the bot monitor many assets continuously in parallel? | WebSocket (if on Stream tier) | | Is the bot a prototype or MVP? | Start with REST polling, migrate to webhooks later |

The builders who get the most out of our data use webhooks to know when to look, and REST to understand what they're looking at. The webhook tells them "Smart Money just flipped long on ETH." The REST call tells them how large the shift is, what other cohorts are doing, and whether liquidation risk supports the move.

That combination turns raw data into a decision pipeline. Your bot doesn't waste cycles asking "anything new?" a thousand times a day. It waits, gets the tap on the shoulder, and acts with full context. That's the architecture worth building.