Integración de Webhooks en Hyperliquid: patrones y ejemplos prácticos

Al construir sistemas de trading automatizado, una arquitectura orientada a eventos suele ser más eficiente que hacer polling constante. En el caso de Hyperliquid, el protocolo no ofrece un mecanismo clásico de HTTP Webhook nativo. Por eso, los desarrolladores normalmente replican ese comportamiento usando suscripciones por WebSocket o escucha de eventos on-chain, y luego reenvían esos eventos a un endpoint HTTP propio.

En esta guía revisamos los principales patrones para “webhookizar” Hyperliquid y mostramos ejemplos de implementación que puedes adaptar a tu stack.

Por qué usar un patrón tipo Webhook

Los problemas principales del polling REST tradicional son:

• Consume más ancho de banda y recursos de cómputo cuando se consulta con alta frecuencia.
• El intervalo de polling introduce una latencia inevitable en la reacción a eventos.
• Al monitorear múltiples cuentas, la cantidad de consultas crece de forma lineal.

Las ventajas de un enfoque Webhook / event-driven son:

• Los eventos se procesan apenas ocurren, con menor latencia.
• El servidor no necesita mantener estados complejos de polling.
• La arquitectura queda más clara y escala mejor a escenarios con varias cuentas y estrategias.

La documentación oficial de WebSocket de Hyperliquid es la referencia central para construir este tipo de arquitectura orientada a eventos.

Patrón 1: Suscripción WebSocket a HTTP Webhook

Este es el patrón más común: ejecutas un “servicio puente” local o en la nube, te suscribes al WebSocket de Hyperliquid y reenvías los eventos recibidos mediante HTTP POST a consumidores downstream, como bots de trading, sistemas de alertas o servicios de escritura en base de datos.

Arquitectura:

Hyperliquid WS --> [Servicio puente] --> HTTP POST --> [Consumidor downstream]

Ejemplo de servicio puente con 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:
        # Suscribirse a actualizaciones de órdenes del usuario
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Suscribirse a ejecuciones / fills del usuario
        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()

Patrón 2: Funciones serverless

Para eventos de baja frecuencia, como un resumen diario u horario de funding, puedes usar funciones serverless en lugar de mantener una conexión WebSocket persistente. Una función en AWS Lambda, Cloudflare Workers u otra plataforma puede despertarse por cron, consultar la API REST de Hyperliquid, procesar los datos y enviar una alerta a Slack, Telegram o un sistema interno.

Ejemplo con Cloudflare Worker ejecutado cada hora por cron:

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

    // Detectar monedas con funding superior a 0.05% en valor absoluto
    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: `Alerta de funding alto: ${highFunding.map(x => `${x.coin} ${(x.rate*100).toFixed(4)}%`).join(", ")}`
        }),
      });
    }
  }
};

Este enfoque no reemplaza al WebSocket para trading en tiempo real, pero es práctico para monitoreo de baja frecuencia y alertas operativas.

Patrón 3: Escucha de eventos on-chain

Como los datos de trading de Hyperliquid se escriben on-chain, en teoría también puedes escuchar eventos de la red para obtener registros completos de transacciones. La documentación de Hyperliquid ofrece una interfaz RPC compatible con EVM, por lo que puedes usar herramientas estándar de Ethereum como ethers.js o web3.py para suscribirte a logs y bloques.

Ejemplo básico con Python:

from web3 import Web3

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

# Escuchar bloques recientes
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)
    for tx in block.transactions:
        # Filtrar por la dirección del contrato relevante de Hyperliquid
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"Nueva transacción: {tx['hash'].hex()}")

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

Este patrón puede ser útil para indexación, auditoría o conciliación de datos, aunque para señales operativas de trading normalmente WebSocket sigue siendo más directo.

Confiabilidad: reintentos e idempotencia

En producción, el consumidor del Webhook puede no estar disponible temporalmente. Por eso conviene implementar reintentos con backoff exponencial:

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

Además, el consumidor downstream debería procesar los mensajes de forma idempotente para evitar duplicados causados por reintentos de red. Una práctica común es incluir un ID único por evento y registrar en la base de datos cuáles ya fueron procesados.

Integración con monitoreo y alertas

Conectar los eventos Webhook a un sistema de monitoreo te ayuda a detectar rápido situaciones como:

• Eventos de liquidación (liquidation): disparar una alerta inmediata y evaluar si hace falta ajustar margen.
• Cambios grandes en funding: identificar costos de posición que se salen de lo esperado.
• Órdenes rechazadas: revisar si el margen disponible, el tamaño o los parámetros de la orden son correctos.

Puedes usar Grafana junto con el servicio puente descrito arriba para construir dashboards de ejecución, exposición, funding y errores.

OneKey Wallet: ejecución más segura para trading automatizado

Un sistema automatizado basado en Webhooks muchas veces termina disparando transacciones on-chain o acciones de trading. En esa parte, la seguridad de las claves privadas es uno de los mayores riesgos. OneKey hardware wallet ofrece firma por hardware mediante USB o Bluetooth, de modo que, incluso si un script automatizado se ve comprometido, el atacante no puede firmar transacciones sin el dispositivo físico.

Para escenarios de mayor frecuencia, puedes combinar el mecanismo de Agent address de Hyperliquid —por ejemplo, con una hot wallet operativa y una hardware wallet como Vault— para buscar un equilibrio entre seguridad y eficiencia.

OneKey Perps funciona como una capa práctica de ejecución para traders de perpetuos. Al combinarlo con tu sistema de automatización por Webhook, puedes estructurar una infraestructura de trading más ordenada, con mejor separación entre monitoreo, señales, ejecución y custodia.

Si quieres probar este flujo de forma prudente, descarga OneKey, configura tu wallet y usa OneKey Perps para operar perpetuos con una experiencia más segura y controlada.

Preguntas frecuentes

Q1: ¿Hyperliquid soporta HTTP Webhooks de forma nativa?

No. Hasta ahora, Hyperliquid no ofrece HTTP Webhooks nativos. Las notificaciones en tiempo real se implementan mediante WebSocket, y el desarrollador debe construir su propia capa puente de “WS a HTTP”.

Q2: ¿WebSocket puede tener problemas de rendimiento al monitorear muchas cuentas?

Cada cuenta necesita su propia suscripción WebSocket. Para decenas de cuentas, las conexiones concurrentes suelen ser manejables. Para miles de cuentas, conviene usar connection pooling y frameworks asíncronos como asyncio.

Q3: ¿Cómo evito que falsifiquen mensajes Webhook?

Si el servicio puente y el consumidor son tuyos, la fuente del mensaje es tu propio listener WebSocket. Aun así, si expones el endpoint a servicios externos o terceros, deberías agregar verificación con firma HMAC u otro mecanismo de autenticación.

Q4: ¿La versión gratuita de Cloudflare Workers alcanza para monitorear Hyperliquid?

La versión gratuita tiene límites diarios de requests, pero para monitoreo de baja frecuencia, como una ejecución por hora, suele ser suficiente. Para monitoreo en tiempo real o cargas altas, considera un plan pago o infraestructura propia.

Q5: ¿Cuál es la diferencia entre userFills y orderUpdates?

userFills envía detalles cuando una orden se ejecuta, incluyendo precio, cantidad y comisiones. orderUpdates envía cambios de estado de la orden, como envío, ejecución parcial o cancelación. En la práctica, ambos eventos se complementan.

Aviso de riesgo

Este artículo es una referencia técnica de arquitectura y no constituye asesoría financiera, legal ni de inversión. Los sistemas de trading automatizado pueden fallar por errores de código, problemas de red, mala gestión de claves, parámetros incorrectos o condiciones extremas de mercado. Prueba todo en entornos controlados antes de desplegarlo en producción y opera solo con riesgos que entiendas.