Hyperliquid Webhook-Integration: Muster, Architektur und Beispiele

Beim Aufbau automatisierter Trading-Systeme ist ein ereignisgetriebener Ansatz meist effizienter als klassisches Polling. Bei Hyperliquid gibt es allerdings keinen nativen HTTP-Webhook-Mechanismus im traditionellen Sinn. Entwickler müssen daher WebSocket-Subscriptions oder On-Chain-Event-Listening nutzen, um einen ähnlichen Echtzeit-Push-Effekt zu erreichen, und die Events anschließend an eigene HTTP-Endpunkte weiterleiten.

In diesem Artikel schauen wir uns die wichtigsten Integrationsmuster an, mit denen du Hyperliquid praktisch „Webhook-fähig“ machst — inklusive umsetzbarer Code-Beispiele.

Warum ein Webhook-Muster sinnvoll ist

Die typischen Probleme von REST-Polling:

• Hochfrequentes Polling verschwendet Bandbreite und Rechenressourcen
• Das Polling-Intervall erzeugt immer eine gewisse Reaktionsverzögerung
• Beim Monitoring mehrerer Accounts wächst die Anzahl der Requests linear mit

Vorteile eines Webhook- bzw. Event-driven-Ansatzes:

• Events werden direkt bei Auftreten verarbeitet, mit sehr niedriger Latenz
• Der Server muss keinen Polling-Status verwalten
• Die Architektur ist klarer und lässt sich einfacher auf mehrere Accounts und Strategien erweitern

Die offiziellen Hyperliquid-WebSocket-Dokumente sind die zentrale Referenz für eine eventgetriebene Architektur.

Muster 1: WebSocket-Subscription zu HTTP-Webhook

Das ist das häufigste Modell: Du betreibst lokal oder in der Cloud einen kleinen „Bridge Service“, der den Hyperliquid WebSocket abonniert, eingehende Events formatiert und per HTTP POST an nachgelagerte Systeme weiterleitet — zum Beispiel Trading-Bots, Alerting-Systeme oder Datenbank-Writer.

Architektur:

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

Bridge-Service-Beispiel mit Python + FastAPI:

import asyncio
import json
import httpx
import websockets
from fastapi import FastAPI
import threading

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:
        # User-Order-Updates abonnieren
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Fills / ausgeführte Trades abonnieren
        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()

Muster 2: Serverless-Funktionen

Für Events mit niedriger Frequenz, etwa eine tägliche oder stündliche Funding-Rate-Auswertung, kann eine zeitgesteuerte Serverless-Funktion eine dauerhafte WebSocket-Verbindung ersetzen. Eine Cloud Function wie AWS Lambda oder Cloudflare Workers wird nach Zeitplan ausgeführt, fragt die Hyperliquid REST API ab, verarbeitet die Daten und pusht sie anschließend an Slack, Telegram oder interne Systeme.

Cloudflare-Worker-Beispiel, das stündlich per Cron läuft:

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();

    // Coins mit Funding Rate über 0,05% finden
    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: `Hohe Funding Rate: ${highFunding.map(x => `${x.coin} ${(x.rate*100).toFixed(4)}%`).join(", ")}`
        }),
      });
    }
  }
};

Muster 3: On-Chain-Event-Listening / Indexing

Da Handelsdaten bei Hyperliquid on-chain geschrieben werden, kannst du theoretisch auch Chain-Events auslesen, um vollständige Trading-Historien oder bestimmte Transaktionen zu erfassen. Die Hyperliquid-Dokumentation stellt dafür eine EVM-kompatible RPC-Schnittstelle bereit, sodass du Standard-Tools aus dem Ethereum-Ökosystem verwenden kannst, etwa ethers.js oder web3.py.

from web3 import Web3

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

# Neueste Blöcke beobachten
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)
    for tx in block.transactions:
        # Nach Hyperliquid-Contract-Adresse filtern
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"Neue Transaktion: {tx['hash'].hex()}")

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

Zuverlässigkeit: Retries und Idempotenz

In einer Produktionsumgebung kann der Webhook-Empfänger zeitweise nicht erreichbar sein. Deshalb solltest du Retry-Logik einbauen:

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()

Gleichzeitig sollte der Downstream Consumer idempotent arbeiten. Sonst können Netzwerk-Retries dazu führen, dass ein Event doppelt verarbeitet wird. In der Praxis gibst du jedem Event eine eindeutige ID und speicherst in deiner Datenbank, welche IDs bereits verarbeitet wurden.

Monitoring und Alerts integrieren

Wenn du Webhook-Events an ein Monitoring-System weiterleitest, kannst du kritische Zustände schneller erkennen, zum Beispiel:

• Liquidations-Events vom Typ liquidation: sofortige Alerts, um zu prüfen, ob zusätzliches Margin-Management nötig ist
• Große Änderungen bei Funding Rates: mögliche Abweichungen bei den erwarteten Haltekosten
• Abgelehnte Orders: Prüfung, ob genügend Margin vorhanden ist oder ob andere Restriktionen greifen

Mit Grafana und dem beschriebenen Bridge Service lässt sich ein vollständiges Monitoring-Dashboard für deine Hyperliquid-Aktivität aufbauen.

OneKey Wallet: Automatisierung sicher ausführen

Ein automatisiertes Webhook-System endet häufig nicht beim Monitoring, sondern kann auch On-Chain-Transaktionen oder Trading-Aktionen auslösen. Genau hier ist Private-Key-Sicherheit der wichtigste Risikofaktor.

Die OneKey Hardware Wallet bietet Hardware-Signing über USB oder Bluetooth. Selbst wenn ein Automatisierungsskript kompromittiert wird, kann ein Angreifer ohne physisches Gerät keine Transaktionen signieren.

Für höherfrequente Automatisierung kannst du Hyperliquids Agent-Adressmechanismus nutzen — etwa mit Hot-Wallet-Signatur für operative Abläufe und einer Hardware Wallet als Vault. So lässt sich ein praktikabler Kompromiss zwischen Sicherheit und Effizienz herstellen.

OneKey Perps bietet Perpetual-Tradern eine sichere Ausführungsebene und kann zusammen mit deiner Webhook-Automatisierung Teil einer robusteren Trading-Infrastruktur sein. Wenn du Hyperliquid-Workflows sicherer aufsetzen möchtest, lade OneKey herunter, richte deine Wallet ein und teste OneKey Perps zunächst mit klar begrenztem Risiko.

Häufige Fragen

Q1: Unterstützt Hyperliquid native HTTP-Webhooks?

Nein. Aktuell bietet Hyperliquid keine nativen HTTP-Webhooks. Echtzeit-Push läuft über WebSocket-Subscriptions. Wenn du HTTP-Webhooks brauchst, musst du selbst eine Bridge von WebSocket zu HTTP bauen.

Q2: Gibt es bei WebSocket-Verbindungen Probleme beim Monitoring mehrerer Accounts?

Pro Account brauchst du eine eigene WebSocket-Subscription. Für einige Dutzend Accounts ist das normalerweise gut machbar. Bei Tausenden Accounts solltest du Connection Pooling und ein asynchrones Framework wie asyncio einsetzen.

Q3: Wie schütze ich Webhook-Nachrichten vor Fälschung?

Wenn die Bridge und der WebSocket-Listener unter deiner Kontrolle stehen, ist die Quelle intern bereits begrenzt. Sobald du Webhooks jedoch externen Drittparteien zugänglich machst, solltest du HMAC-Signaturen oder ein ähnliches Verifikationsverfahren verwenden.

Q4: Reicht die kostenlose Version von Cloudflare Workers für Hyperliquid-Monitoring?

Cloudflare Workers hat im kostenlosen Tarif ein tägliches Request-Limit von 100.000 Requests. Für niedrigfrequentes Monitoring, etwa einmal pro Stunde, reicht das in der Regel aus. Für hochfrequentes Echtzeit-Monitoring sind ein kostenpflichtiger Tarif oder ein eigener Server sinnvoller.

Q5: Was ist der Unterschied zwischen userFills und orderUpdates?

userFills sendet Details, wenn eine Order ausgeführt wurde, etwa Preis, Menge und Gebühren. orderUpdates meldet Statusänderungen von Orders, zum Beispiel eingereicht, teilweise ausgeführt oder storniert. Beide Event-Typen ergänzen sich.

Risikohinweis

Dieser Artikel dient als technische Architektur-Referenz und ist keine Anlage-, Rechts- oder Finanzberatung. Automatisierte Trading-Systeme bergen Risiken wie Codefehler, Fehlkonfigurationen, Netzwerkprobleme und unerwartetes Marktverhalten. Teste deine Setups gründlich, bevor du sie in einer Produktionsumgebung einsetzt.