Hyperliquid Webhook 통합 패턴 완전 정리
자동매매 시스템을 설계할 때는 일정 간격으로 API를 계속 호출하는 폴링 방식보다, 이벤트가 발생했을 때만 처리하는 “이벤트 드리븐” 구조가 더 효율적인 경우가 많습니다. Hyperliquid의 경우 전통적인 의미의 HTTP Webhook 푸시 기능이 프로토콜에 기본 내장되어 있지는 않습니다. 따라서 개발자는 WebSocket 구독이나 온체인 이벤트 모니터링을 통해 Webhook과 유사한 실시간 알림 흐름을 만들고, 해당 이벤트를 자체 HTTP 엔드포인트로 전달하는 방식으로 구현해야 합니다.
이 글에서는 Hyperliquid를 “Webhook처럼” 연동하는 대표적인 패턴을 정리하고, 실제 구현에 참고할 수 있는 코드 예시를 함께 살펴봅니다.
왜 Webhook 패턴이 필요한가요?
기존 REST 폴링 방식에는 몇 가지 구조적인 한계가 있습니다.
- 고빈도 폴링은 대역폭과 컴퓨팅 리소스를 낭비합니다.
- 폴링 주기 때문에 이벤트 반응에 필연적인 지연이 생깁니다.
- 여러 계정을 동시에 모니터링할 경우 폴링 요청 수가 계정 수에 비례해 증가합니다.
반면 Webhook 또는 이벤트 드리븐 방식은 다음과 같은 장점이 있습니다.
- 이벤트 발생 시 즉시 전달되어 지연이 낮습니다.
- 서버가 별도의 폴링 상태를 계속 관리할 필요가 없습니다.
- 다계정, 다전략 구조로 확장하기 쉽고 아키텍처가 명확해집니다.
Hyperliquid에서 이벤트 기반 구조를 구현하려면 Hyperliquid 공식 WebSocket 문서를 핵심 참고 자료로 삼는 것이 좋습니다.
패턴 1: WebSocket 구독을 HTTP Webhook으로 변환하기
가장 일반적인 방식은 로컬 서버나 클라우드 환경에서 “브리지 서비스”를 실행하는 것입니다. 이 서비스가 Hyperliquid WebSocket을 구독하고, 수신한 이벤트를 포맷한 뒤 HTTP POST 요청으로 하위 시스템에 전달합니다. 하위 시스템은 트레이딩 봇, 알림 시스템, 데이터베이스 적재 서비스 등이 될 수 있습니다.
아키텍처는 다음과 같습니다.
Hyperliquid WS --> [브리지 서비스] --> HTTP POST --> [하위 소비자]
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:
# 사용자 주문 업데이트 구독
await ws.send(json.dumps({
"method": "subscribe",
"subscription": {"type": "orderUpdates", "user": user_address}
}))
# 사용자 체결 내역 구독
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()
이 구조의 핵심은 Hyperliquid WebSocket에서 받은 이벤트를 내부 시스템이 이해할 수 있는 HTTP Webhook 형식으로 변환하는 것입니다. 이후 하위 시스템에서는 동일한 HTTP 이벤트 인터페이스만 처리하면 되므로, 전략 로직이나 알림 로직을 분리하기 쉽습니다.
패턴 2: 서버리스 함수 방식
모든 이벤트를 실시간으로 처리해야 하는 것은 아닙니다. 예를 들어 일별 펀딩비 요약, 특정 시간마다 수행하는 시장 상태 점검처럼 저빈도 이벤트라면 장시간 WebSocket 연결을 유지하지 않고 서버리스 함수를 사용할 수 있습니다.
AWS Lambda나 Cloudflare Workers 같은 클라우드 함수는 정해진 시간에 실행되어 Hyperliquid REST API를 조회하고, 결과를 Slack, Telegram 또는 내부 시스템으로 전달할 수 있습니다.
아래는 Cloudflare Worker에서 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();
// 펀딩비가 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: `높은 펀딩비 알림: ${highFunding.map(x => `${x.coin} ${(x.rate*100).toFixed(4)}%`).join(", ")}`
}),
});
}
}
};
이 방식은 실시간성은 WebSocket보다 떨어지지만, 인프라 운영 부담이 낮고 비용 관리가 쉽습니다. 따라서 고빈도 자동매매보다는 리스크 모니터링, 펀딩비 알림, 정기 리포트 생성 같은 작업에 적합합니다.
패턴 3: 온체인 이벤트 모니터링
Hyperliquid의 거래 데이터는 온체인에 기록되므로, 이론적으로는 온체인 이벤트를 모니터링해 전체 거래 기록을 추적할 수 있습니다. Hyperliquid 문서에서는 EVM 호환 RPC 인터페이스를 제공하므로, ethers.js나 web3.py 같은 표준 이더리움 도구로 로그 이벤트를 구독할 수 있습니다.
from web3 import Web3
HL_RPC = "https://rpc.hyperliquid.xyz/evm"
w3 = Web3(Web3.HTTPProvider(HL_RPC))
# 최신 블록 모니터링
def handle_new_block(block_number):
block = w3.eth.get_block(block_number, full_transactions=True)
for tx in block.transactions:
# Hyperliquid 관련 컨트랙트 주소 필터링
if tx.get("to") == "0xHYPERLIQUID_CONTRACT":
print(f"새 거래: {tx['hash'].hex()}")
w3.eth.subscribe("newHeads", handle_new_block)
온체인 인덱싱 방식은 데이터 무결성과 장기 기록 추적에 유리하지만, 단순 WebSocket 구독보다 구현 난이도가 높습니다. 또한 실제 운영 환경에서는 컨트랙트 주소, 이벤트 ABI, 재조직 대응, 누락 이벤트 보정 로직 등을 함께 고려해야 합니다.
안정성 확보: 재시도와 멱등성
프로덕션 환경에서는 Webhook 수신 측 서비스가 일시적으로 응답하지 않을 수 있습니다. 따라서 브리지 서비스에는 재시도 로직을 넣는 것이 좋습니다.
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()
동시에 하위 소비자도 멱등 처리를 구현해야 합니다. 네트워크 오류로 인해 동일 이벤트가 여러 번 전송될 수 있기 때문입니다. 일반적으로 각 이벤트에 고유 ID를 포함하고, 데이터베이스에 이미 처리한 ID를 기록해 중복 소비를 방지합니다.
모니터링과 알림 연동
Webhook 이벤트를 모니터링 시스템에 연결하면 다음과 같은 이상 상황을 빠르게 감지할 수 있습니다.
- 강제청산 이벤트(
liquidation유형): 즉시 알림을 보내고 증거금 보충 필요 여부를 점검합니다. - 큰 폭의 펀딩비 변화: 포지션 유지 비용이 예상 범위를 벗어나는지 확인합니다.
- 주문 거절: 증거금 부족, 주문 파라미터 오류, 계정 상태 문제 등을 점검합니다.
앞서 설명한 브리지 서비스와 Grafana를 함께 사용하면 Hyperliquid 계정 및 전략 상태를 한눈에 확인할 수 있는 모니터링 대시보드를 구성할 수 있습니다.
OneKey 지갑: 자동매매 실행 단계의 보안 강화
자동화된 Webhook 시스템은 결국 온체인 거래 또는 파생상품 주문 실행으로 이어지는 경우가 많습니다. 이 단계에서 가장 중요한 리스크는 개인키 보안입니다. 자동화 스크립트나 서버가 침해될 경우, 개인키가 그대로 노출되어 자산 손실로 이어질 수 있습니다.
OneKey 하드웨어 지갑은 USB 또는 블루투스 연결 기반의 하드웨어 서명 환경을 제공합니다. 자동화 스크립트가 공격을 받더라도, 공격자는 물리적 기기 없이 임의로 거래에 서명할 수 없습니다.
고빈도 자동화 환경에서는 Hyperliquid의 Agent 주소 메커니즘을 활용할 수 있습니다. 예를 들어 핫월렛 서명과 하드웨어 지갑 기반 Vault 구조를 조합하면, 실행 효율성과 키 보안 사이에서 현실적인 균형을 잡을 수 있습니다.
OneKey Perps는 무기한 선물 거래자를 위한 안전한 실행 레이어로 활용할 수 있습니다. 직접 구축한 Webhook 자동화 시스템과 함께 사용하면, 이벤트 수집부터 주문 실행, 키 보안까지 이어지는 보다 일관된 트레이딩 인프라를 구성할 수 있습니다.
자동화 거래를 검토하고 있다면 OneKey를 다운로드해 지갑 보안 환경을 먼저 점검하고, OneKey Perps를 통해 Hyperliquid 기반 무기한 선물 워크플로를 신중하게 테스트해 보세요.
자주 묻는 질문
Q1. Hyperliquid는 HTTP Webhook 푸시를 기본 지원하나요?
아니요. 현재 Hyperliquid는 기본 HTTP Webhook을 제공하지 않습니다. 실시간 이벤트 푸시는 WebSocket을 통해 구현되며, 개발자가 직접 “WebSocket to HTTP” 브리지 레이어를 구축해야 합니다.
Q2. 여러 계정을 모니터링하면 WebSocket 성능 문제가 생기지 않나요?
각 계정마다 독립적인 WebSocket 구독이 필요합니다. 수십 개 계정 수준에서는 동시 연결이 충분히 가능합니다. 수천 개 계정을 다뤄야 한다면 연결 풀, 비동기 프레임워크, 큐 기반 처리 구조 등을 사용해 최적화하는 것이 좋습니다.
Q3. Webhook 메시지가 위조되지 않도록 하려면 어떻게 해야 하나요?
브리지 서비스에서 메시지 출처가 직접 운영하는 WebSocket 리스너라면 내부적으로는 별도 검증이 필요하지 않을 수 있습니다. 다만 Webhook 엔드포인트를 외부 제3자에게 노출한다면 HMAC 서명 검증 같은 인증 메커니즘을 추가하는 것이 안전합니다.
Q4. Cloudflare Workers 무료 플랜으로 Hyperliquid 모니터링이 가능한가요?
Workers 무료 플랜에는 일일 요청 수 제한이 있습니다. 저빈도 모니터링, 예를 들어 매시간 실행되는 작업에는 충분할 수 있습니다. 반면 고빈도 실시간 모니터링에는 유료 플랜이나 자체 서버 구성이 더 적합합니다.
Q5. WebSocket 구독의 userFills와 orderUpdates는 무엇이 다른가요?
userFills는 주문이 체결될 때 체결가, 수량, 수수료 같은 체결 상세 정보를 전달합니다. orderUpdates는 주문 제출, 부분 체결, 취소 등 주문 상태 변화에 대한 이벤트를 전달합니다. 두 이벤트는 서로 보완적으로 사용하는 것이 좋습니다.
리스크 안내
이 글은 기술 아키텍처 참고 자료이며 투자 조언이 아닙니다. 자동매매 시스템에는 코드 결함, 네트워크 장애, API 변경, 잘못된 주문 실행 등 다양한 위험이 존재합니다. 충분한 테스트와 리스크 관리 절차를 거친 뒤 신중하게 프로덕션 환경에 배포하시기 바랍니다.
