Comprendre les modèles d’intégration Webhook pour Hyperliquid

Quand tu construis un système de trading automatisé, une architecture « event-driven » est souvent plus efficace qu’un simple polling REST. Dans le cas d’Hyperliquid, le protocole ne propose pas, au sens classique, de mécanisme HTTP Webhook natif. Les développeurs doivent donc s’appuyer sur les abonnements WebSocket ou sur l’écoute d’événements on-chain pour obtenir un comportement proche d’un Webhook en temps réel, puis relayer ces événements vers leurs propres endpoints HTTP.

Cet article passe en revue les principaux modèles d’intégration « webhook-like » pour Hyperliquid, avec des exemples de code directement exploitables.

Pourquoi utiliser un modèle Webhook ?

Les limites du polling REST classique :

• Le polling fréquent consomme inutilement de la bande passante et des ressources de calcul
• L’intervalle de polling introduit une latence structurelle dans la réaction aux événements
• En surveillance multi-comptes, le nombre de requêtes augmente de manière linéaire

Les avantages d’un modèle Webhook / event-driven :

• Les événements sont poussés dès qu’ils se produisent, avec une latence très faible
• Le serveur n’a pas besoin de maintenir un état de polling complexe
• L’architecture est plus lisible et s’étend mieux aux scénarios multi-comptes et multi-stratégies

La documentation WebSocket officielle d’Hyperliquid reste la référence principale pour mettre en place ce type d’architecture.

Modèle 1 : abonnement WebSocket vers HTTP Webhook

C’est le schéma le plus courant : tu fais tourner un service « bridge » localement ou dans le cloud. Ce service s’abonne au WebSocket d’Hyperliquid, formate les événements reçus, puis les relaie en HTTP POST vers un consommateur en aval : bot de trading, système d’alerte, service d’écriture en base de données, etc.

Architecture :

Hyperliquid WS --> [service bridge] --> HTTP POST --> [consommateur aval]

Exemple de service bridge en 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:
        # Abonnement aux mises à jour d’ordres utilisateur
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Abonnement aux exécutions utilisateur
        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()

Modèle 2 : fonctions serverless

Pour les événements peu fréquents, par exemple un résumé quotidien des funding rates, tu peux remplacer une connexion WebSocket longue durée par une fonction serverless déclenchée à intervalle régulier.

Une fonction cloud comme AWS Lambda ou Cloudflare Workers peut se réveiller selon un cron, interroger l’API REST d’Hyperliquid, traiter les données, puis envoyer le résultat vers Slack, Telegram ou un système interne.

Exemple Cloudflare Worker exécuté toutes les heures :

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

    // Identifier les actifs dont le funding rate dépasse 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: `Alerte funding élevé : ${highFunding.map(x => `${x.coin} ${(x.rate * 100).toFixed(4)}%`).join(", ")}`
        }),
      });
    }
  }
};

Modèle 3 : écoute d’événements on-chain

Comme les données de trading d’Hyperliquid sont inscrites on-chain, il est théoriquement possible d’écouter les événements de la chaîne pour récupérer un historique complet des transactions.

La documentation Hyperliquid fournit une interface RPC compatible EVM, ce qui permet d’utiliser des outils Ethereum standards comme ethers.js ou web3.py pour s’abonner aux logs et aux nouveaux blocs.

from web3 import Web3

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

# Écoute des derniers blocs
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)

    for tx in block.transactions:
        # Filtrer l’adresse du contrat Hyperliquid
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"Nouvelle transaction : {tx['hash'].hex()}")

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

Fiabilité : retries et idempotence

En production, le consommateur Webhook en aval peut être temporairement indisponible. Ton bridge doit donc intégrer une logique de retry :

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

Côté consommateur, il faut aussi prévoir un traitement idempotent afin d’éviter qu’un retry réseau ne provoque une double consommation du même événement. Une approche simple consiste à inclure un identifiant unique dans chaque événement, puis à enregistrer en base les IDs déjà traités.

Monitoring et alertes

En connectant tes événements Webhook à un système de monitoring, tu peux détecter rapidement plusieurs situations sensibles :

• Événements de liquidation, par exemple de type liquidation : déclencher une alerte immédiate et vérifier si un ajustement de marge est nécessaire
• Variations importantes des funding rates : surveiller si le coût de portage dépasse les attentes
• Rejets d’ordres : vérifier si la marge disponible est suffisante

Tu peux par exemple utiliser Grafana avec le service bridge décrit plus haut pour construire un tableau de bord complet.

OneKey Wallet : exécuter l’automatisation sans négliger la sécurité

Un système Webhook automatisé finit souvent par déclencher des transactions on-chain. À ce stade, la sécurité des clés privées devient le principal point de risque.

OneKey Hardware Wallet propose une signature matérielle via USB ou Bluetooth. Même si un script automatisé est compromis, un attaquant ne peut pas signer de transaction sans accès physique à l’appareil.

Pour les scénarios d’automatisation à haute fréquence, tu peux utiliser le mécanisme d’Agent address d’Hyperliquid : un hot wallet signe les opérations courantes, tandis que le hardware wallet reste utilisé comme Vault. Cela permet de trouver un compromis plus équilibré entre sécurité opérationnelle et efficacité d’exécution.

OneKey Perps fournit une couche d’exécution pratique pour les traders de contrats perpétuels. En l’associant à ton système d’automatisation Webhook, tu peux construire une infrastructure de trading plus cohérente, tout en gardant une attention forte sur la gestion des clés et des risques.

Tu peux télécharger OneKey et tester OneKey Perps pour mettre en place ton workflow de manière plus sécurisée, sans promesse de rendement ni automatisation aveugle.

FAQ

Q1 : Hyperliquid prend-il nativement en charge les Webhooks HTTP ?

Non. À ce jour, Hyperliquid ne propose pas de Webhook HTTP natif. Les flux temps réel passent par WebSocket. Les développeurs doivent donc construire eux-mêmes une couche bridge « WebSocket vers HTTP ».

Q2 : Les connexions WebSocket posent-elles problème en surveillance multi-comptes ?

Chaque compte nécessite un abonnement WebSocket distinct. Pour quelques dizaines de comptes, les connexions concurrentes restent tout à fait gérables. Pour plusieurs milliers de comptes, il vaut mieux utiliser un pool de connexions et un framework asynchrone comme asyncio.

Q3 : Comment sécuriser les messages Webhook contre la falsification ?

Si ton bridge WebSocket est sous ton contrôle, la source des messages est déjà maîtrisée. En revanche, si tu exposes un endpoint Webhook à des tiers externes, ajoute une vérification par signature HMAC pour authentifier les requêtes.

Q4 : La version gratuite de Cloudflare Workers suffit-elle pour surveiller Hyperliquid ?

La version gratuite de Workers impose une limite de requêtes quotidiennes, généralement indiquée à 100 000 requêtes par jour. Pour une surveillance basse fréquence, par exemple une exécution horaire, cela suffit largement. Pour un monitoring temps réel intensif, il est préférable d’envisager une offre payante ou un serveur dédié.

Q5 : Quelle est la différence entre userFills et orderUpdates ?

userFills pousse les détails lorsqu’un ordre est exécuté : prix d’exécution, quantité, frais, etc. orderUpdates pousse les changements d’état d’un ordre : soumission, exécution partielle, annulation, rejet, etc. Les deux flux sont complémentaires.

Risques à garder en tête

Cet article est une référence technique d’architecture et ne constitue pas un conseil en investissement. Les systèmes de trading automatisé comportent des risques : bugs de code, pannes réseau, erreurs de configuration, exécution inattendue ou mauvaise gestion des clés. Teste soigneusement ton système avant tout déploiement en production et limite toujours les permissions accordées aux composants automatisés.