Hyperliquid Webhook: guia completo de padrões de integração

Ao construir sistemas de trading automatizado, uma arquitetura orientada a eventos costuma ser mais eficiente do que polling constante. No caso da Hyperliquid, como o protocolo não oferece um mecanismo tradicional de push via HTTP Webhook, desenvolvedores normalmente implementam um efeito semelhante usando assinaturas via WebSocket ou monitoramento de eventos on-chain, e então encaminham esses eventos para endpoints HTTP próprios.

Este guia resume os principais padrões para “transformar” eventos da Hyperliquid em webhooks e traz exemplos práticos de implementação.

Por que usar um modelo de Webhook

Os principais problemas do polling via REST são:

• Polling em alta frequência desperdiça banda e recursos computacionais
• O intervalo entre requisições cria uma latência inevitável na resposta a eventos
• Ao monitorar várias contas em paralelo, o número de chamadas cresce de forma linear

As vantagens de um modelo Webhook / event-driven incluem:

• Eventos são enviados assim que ocorrem, com latência muito baixa
• O servidor não precisa manter estado de polling
• A arquitetura fica mais clara e escala melhor para múltiplas contas e estratégias

A documentação oficial de WebSocket da Hyperliquid é a principal referência para implementar esse tipo de arquitetura orientada a eventos.

Modelo 1: assinatura WebSocket convertida em HTTP Webhook

Este é o padrão mais comum: você roda um “serviço ponte” localmente ou na nuvem, assina eventos da Hyperliquid via WebSocket, formata as mensagens recebidas e as encaminha por HTTP POST para consumidores downstream, como bots de trading, sistemas de alerta ou serviços de gravação em banco de dados.

Arquitetura:

Hyperliquid WS --> [Serviço ponte] --> HTTP POST --> [Consumidor downstream]

Exemplo de serviço ponte com 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:
        # Assina atualizações de ordens do usuário
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "orderUpdates", "user": user_address}
        }))

        # Assina histórico de fills do usuário
        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()

Modelo 2: funções serverless

Para eventos de baixa frequência, como um resumo diário de funding rate, você pode usar funções serverless acionadas por cron em vez de manter uma conexão WebSocket persistente. Uma função em AWS Lambda ou Cloudflare Workers pode ser executada em intervalos definidos, consultar a API REST da Hyperliquid, processar os dados e enviar alertas para Slack, Telegram ou sistemas internos.

Exemplo com Cloudflare Worker executando a cada hora via 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();

    // Encontra ativos com funding rate acima de 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: `Alerta de funding alto: ${highFunding.map(x => `${x.coin} ${(x.rate * 100).toFixed(4)}%`).join(", ")}`
        }),
      });
    }
  }
};

Modelo 3: monitoramento de eventos on-chain

Como os dados de trading da Hyperliquid são registrados on-chain, em teoria é possível monitorar eventos na rede para obter um registro completo das transações. A documentação da Hyperliquid oferece uma interface RPC compatível com EVM, permitindo usar ferramentas padrão do ecossistema Ethereum, como ethers.js e web3.py, para assinar eventos de logs.

from web3 import Web3

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

# Monitora novos blocos
def handle_new_block(block_number):
    block = w3.eth.get_block(block_number, full_transactions=True)
    for tx in block.transactions:
        # Filtra pelo endereço do contrato da Hyperliquid
        if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
            print(f"Nova transação: {tx['hash'].hex()}")

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

Confiabilidade: retries e idempotência

Em produção, o consumidor downstream do Webhook pode ficar temporariamente indisponível. Por isso, o serviço ponte deve ter uma lógica 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()

Ao mesmo tempo, o consumidor downstream deve implementar idempotência para evitar processamento duplicado causado por retries de rede. Uma prática comum é incluir um ID único em cada evento e registrar no banco de dados quais IDs já foram processados.

Integração com monitoramento e alertas

Ao conectar eventos de Webhook a um sistema de monitoramento, você consegue identificar rapidamente situações como:

• Eventos de liquidação, como tipo liquidation: disparam alertas imediatos para avaliar se é necessário ajustar margem
• Mudanças relevantes em funding rate: indicam custo de posição acima do esperado
• Ordens rejeitadas: ajudam a verificar se a margem disponível é suficiente

Você pode usar Grafana em conjunto com o serviço ponte descrito acima para criar um painel completo de monitoramento.

OneKey Wallet: execução mais segura para trading automatizado

Sistemas automatizados baseados em Webhook frequentemente acabam disparando transações on-chain. Nesse ponto, a segurança da chave privada se torna um dos maiores riscos. A OneKey Hardware Wallet oferece assinatura em hardware via USB ou Bluetooth, de modo que, mesmo se um script automatizado for comprometido, um invasor não consegue assinar transações sem acesso físico ao dispositivo.

Para cenários de automação mais frequentes, você pode considerar o mecanismo de Agent Address da Hyperliquid, combinando assinatura por hot wallet com uma hardware wallet como Vault, buscando um equilíbrio entre segurança operacional e eficiência.

O OneKey Perps oferece uma camada prática de execução para traders de contratos perpétuos. Em conjunto com sua automação via Webhook, ele pode ajudar a estruturar uma infraestrutura de trading mais segura e organizada, sem abrir mão do controle sobre a custódia e a assinatura.

Baixe o OneKey e teste o OneKey Perps com calma em um ambiente adequado ao seu perfil de risco antes de levar qualquer automação para produção.

Perguntas frequentes

Q1: A Hyperliquid oferece suporte nativo a HTTP Webhook?

Não. Até o momento, a Hyperliquid não oferece HTTP Webhook nativo. As notificações em tempo real são implementadas via WebSocket, e desenvolvedores precisam criar sua própria camada ponte de “WS para HTTP”.

Q2: Conexões WebSocket causam problemas de performance ao monitorar várias contas?

Cada conta precisa de uma assinatura WebSocket separada. Para dezenas de contas, conexões concorrentes costumam ser totalmente viáveis. Para milhares de contas, é recomendável usar pool de conexões e frameworks assíncronos, como asyncio, para otimização.

Q3: Como garantir a segurança das mensagens de Webhook e evitar falsificações?

Se o serviço ponte e o listener WebSocket são controlados por você, a origem da mensagem já está dentro da sua própria infraestrutura. Ainda assim, se o Webhook for exposto a terceiros ou à internet pública, adicione verificação por assinatura HMAC.

Q4: O plano gratuito do Cloudflare Workers é suficiente para monitorar a Hyperliquid?

O plano gratuito do Workers tem limite diário de requisições, normalmente 100 mil requisições por dia. Para monitoramento de baixa frequência, como execução a cada hora, tende a ser suficiente. Para monitoramento em tempo real de alta frequência, considere um plano pago ou um servidor próprio.

Q5: Qual é a diferença entre as assinaturas WebSocket userFills e orderUpdates?

userFills envia detalhes quando uma ordem é executada, incluindo preço de execução, quantidade e taxas. Já orderUpdates envia mudanças de status da ordem, como envio, execução parcial e cancelamento. As duas assinaturas se complementam.

Aviso de risco

Este artigo é uma referência técnica de arquitetura e não constitui recomendação de investimento, consultoria financeira ou orientação jurídica. Sistemas de trading automatizado envolvem riscos como bugs de código, falhas de rede, problemas de integração e perdas financeiras. Teste cuidadosamente antes de implantar qualquer automação em produção.