Hyperliquid Webhook Integration Patterns Explained

When you build an automated trading system, an event-driven architecture is usually more efficient than polling. Hyperliquid docs does not provide a traditional HTTP webhook push mechanism at the protocol level, so developers typically recreate “webhook-like” behavior by subscribing to Hyperliquid WebSocket streams or listening to on-chain events, then forwarding those events to their own HTTP endpoints.

This guide breaks down the main ways to build a Hyperliquid webhook integration, with practical implementation examples you can adapt for trading bots, alerts, monitoring, and internal infrastructure.

Why use a webhook-style architecture?

The main issues with traditional REST polling are:

• High-frequency polling wastes bandwidth and compute resources
• Polling intervals create unavoidable response latency
• Monitoring multiple accounts scales linearly in request volume

A webhook or event-driven model offers several advantages:

• Events are pushed as they happen, reducing latency
• Your backend does not need to maintain polling state
• The architecture is cleaner and easier to scale across multiple accounts and strategies

Hyperliquid’s official WebSocket documentation is the key reference for implementing this type of real-time architecture.

Pattern 1: WebSocket subscription to HTTP webhook

This is the most common approach. You run a bridge service locally or in the cloud. The service subscribes to Hyperliquid WebSocket events, formats the incoming messages, and forwards them via HTTP POST to downstream consumers such as trading bots, alerting systems, or database ingestion services.

Architecture:

Hyperliquid WS --> [Bridge Service] --> HTTP POST --> [Downstream Consumer]

Example bridge service using Python and FastAPI:

import asyncio
import json
import threading

import httpx
import websockets
from fastapi import FastAPI

app = FastAPI()

WEBHOOK_TARGET = "https://your-downstream-service.example.com/events"
WS_URL = "wss://api.hyperliquid.xyz/ws"

async def ws_to_webhook(user_address: str):
    async with websockets.connect(WS_URL) as ws:
        # Subscribe to user order updates
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Subscribe to user fills
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "userFills", "user": user_address}
        }))

        async for raw in ws:
            event = json.loads(raw)
            async with httpx.AsyncClient() as client:
                await client.post(WEBHOOK_TARGET, json=event, timeout=5)

@app.on_event("startup")
def start_ws_listener():
    user_addr = "0xYOUR_ADDRESS"
    thread = threading.Thread(
        target=asyncio.run,
        args=(ws_to_webhook(user_addr),),
        daemon=True
    )
    thread.start()

This pattern is a good fit when you need near-real-time updates for orders, fills, liquidations, or account-level events.

Pattern 2: Serverless scheduled function

For lower-frequency monitoring, such as daily funding-rate summaries or hourly risk checks, you may not need a persistent WebSocket connection. A scheduled serverless function can wake up on a cron schedule, query the Hyperliquid REST API, process the result, and push alerts to Slack, Telegram, or an internal system.

Example Cloudflare Worker that runs hourly:

export default {
  async scheduled(event, env, ctx) {
    const resp = await fetch("https://api.hyperliquid.xyz/info", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ type: "metaAndAssetCtxs" }),
    });

    const [meta, ctxs] = await resp.json();

    // Find markets where the funding rate exceeds 0.05%
    const highFunding = ctxs
      .map((ctx, i) => ({
        coin: meta.universe[i].name,
        rate: parseFloat(ctx.funding),
      }))
      .filter((x) => Math.abs(x.rate) > 0.0005);

    if (highFunding.length > 0) {
      await fetch(env.SLACK_WEBHOOK_URL, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `High funding alert: ${highFunding
            .map((x) => `${x.coin} ${(x.rate * 100).toFixed(4)}%`)
            .join(", ")}`,
        }),
      });
    }
  },
};

This pattern is simple, cheap to operate, and useful for periodic monitoring. For high-frequency execution or real-time account state changes, WebSocket-based infrastructure is usually more appropriate.

Pattern 3: On-chain event listening

Because Hyperliquid trading data is written on-chain, you can also monitor on-chain activity to collect a complete transaction history. Hyperliquid docs provides an EVM-compatible RPC interface, which means standard Ethereum tooling such as ethers.js or web3.py can be used to subscribe to logs or inspect new blocks.

Example using web3.py:

from web3 import Web3

HL_RPC = "https://rpc.hyperliquid.xyz/evm"
w3 = Web3(Web3.HTTPProvider(HL_RPC))

# Listen to the latest blocks
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)

    for tx in block.transactions:
        # Filter for a specific Hyperliquid contract address
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"New transaction: {tx['hash'].hex()}")

w3.eth.subscribe("newHeads", handle_new_block)

On-chain indexing is useful for auditability and historical completeness. For execution-sensitive workflows, it is often combined with WebSocket streams so your system can react quickly while still maintaining a reliable record of chain activity.

Reliability: retries and idempotency

In production, your downstream webhook target may be temporarily unavailable. Your bridge service should implement retries with exponential backoff.

Example retry wrapper:

import httpx
import tenacity

@tenacity.retry(
    stop=tenacity.stop_after_attempt(3),
    wait=tenacity.wait_exponential(multiplier=1, min=1, max=10),
    reraise=True,
)
async def send_webhook(client: httpx.AsyncClient, url: str, payload: dict):
    resp = await client.post(url, json=payload, timeout=5)
    resp.raise_for_status()

Your downstream consumer should also process messages idempotently. Network retries can cause duplicate deliveries, so each event should include a unique ID, and your database should record which IDs have already been processed.

Monitoring and alerts

Forwarding Hyperliquid events into a monitoring stack makes it easier to catch issues quickly. Common alert types include:

• Liquidation events: trigger an immediate alert and assess whether margin needs to be added
• Large funding-rate changes: monitor when position costs move beyond expectations
• Order rejections: check whether margin, size, or account state caused the rejection

A common setup is to connect the bridge service to a metrics pipeline and build dashboards in Grafana.

OneKey Wallet: safer execution for automated trading

Webhook infrastructure often ends with a transaction: placing an order, adjusting margin, or managing a position. At that point, private-key security becomes one of the biggest risks.

OneKey hardware wallets provide hardware-based signing over USB or Bluetooth. Even if an automation script or server is compromised, an attacker cannot sign transactions without access to the physical device.

For higher-frequency automation, Hyperliquid’s Agent address mechanism can help balance speed and security: a hot wallet can be used for agent signing, while the hardware wallet remains the vault-level security layer.

OneKey Perps gives perpetuals traders a practical execution layer that can fit alongside a webhook-based automation stack. You can use your own monitoring and alerting infrastructure while keeping key management and trading execution safer and more controlled.

Download OneKey and try OneKey Perps when you are ready to build a more secure perps workflow.

FAQ

Q1: Does Hyperliquid natively support HTTP webhook pushes?

No. Hyperliquid does not currently provide native HTTP webhooks. Real-time updates are delivered through WebSocket subscriptions, so developers need to build their own WebSocket-to-HTTP bridge if they want webhook-style delivery.

Q2: Will WebSocket connections become a performance issue when monitoring multiple accounts?

Each account requires its own WebSocket subscription. Monitoring dozens of accounts is generally practical with concurrent connections. For thousands of accounts, use connection pooling and an async framework such as asyncio to optimize resource usage.

Q3: How can I secure webhook messages and prevent spoofing?

If the bridge service is fully under your control, the source of the messages is your own WebSocket listener. If you expose webhook endpoints to third parties or external systems, add HMAC signature verification and reject unsigned or invalid requests.

Q4: Is the free tier of Cloudflare Workers enough for Hyperliquid monitoring?

Cloudflare Workers has free-tier request limits, which can be enough for low-frequency monitoring such as hourly checks. For high-frequency or real-time monitoring, a paid plan or self-hosted service is usually more appropriate.

Q5: What is the difference between userFills and orderUpdates?

userFills sends fill details when an order executes, including price, size, and fees. orderUpdates sends order state changes such as submission, partial fill, cancellation, or rejection. In practice, the two streams complement each other.

Risk warning

This article is for technical architecture reference only and is not investment advice. Automated trading systems can fail because of code bugs, network outages, exchange-side changes, incorrect configuration, or market volatility. Test thoroughly before deploying to production and manage risk carefully.