트레이딩 봇은 폴링하면 안 됩니다: Hyperliquid 알림을 위한 Webhook

5초마다 봇이 서버에 ping을 보냅니다. "새로운 거 있어?" 없음. "새로운 거 있어?" 없음. "새로운 거 있어?" 여전히 없음. 그리고 나서 whale 코호트가 BTC에서 순 롱으로 전환하는데, 바로 잡아야 할 움직임이지만 다음 예약된 폴링은 4초 뒤입니다. 그 틈이 진입 기회를 날립니다.

이것이 트레이딩 알림에 REST 폴링을 쓸 때의 근본적인 문제입니다. 작동하긴 하지만, 2분마다 우편함을 확인하는 것과 배달부가 초인종을 누르는 것의 차이입니다. 분석 대시보드나 과거 데이터 조회라면 폴링으로 충분합니다. 코호트 전환과 청산 클러스터가 몇 분 만에 시장을 바꿀 수 있는 Hyperliquid의 이벤트 기반 트레이딩에서는 초인종이 필요합니다.

그 초인종이 바로 webhook입니다. Hyperliquid에서 시장 상황에 반응하는 무언가를 만들고 있다면, webhook을 언제 써야 하는지(그리고 폴링이 오히려 나은 경우는 언제인지) 이해하는 것만으로도 낭비되는 API 호출을 줄이고, 코드를 단순화하고, 반응 속도를 높일 수 있습니다.

폴링의 대가: 봇이 레이트 리밋을 헛되이 소진하는 이유

REST 폴링은 대부분의 트레이딩 봇이 기본으로 택하는 아키텍처입니다. 그럴 만한 이유가 있습니다. 단순하기 때문입니다. 루프를 작성하고, N초마다 GET /cohort-metrics를 호출하고, 응답을 이전 값과 비교해 변화가 있을 때 행동합니다. 코드 열 줄, 봇 외에 별도 인프라도 없습니다.

하지만 단순함에는 숨겨진 비용이 따릅니다. 코호트 포지셔닝, 청산 리스크, 펀딩 레이트 세 개의 엔드포인트를 60초마다 폴링하면 하루 4,320건의 API 요청이 발생합니다. 월 50,000건 할당량인 Pulse 플랜에서는 폴링만으로 약 11일 만에 전체 한도를 소진하고, 임시 조회나 과거 분석에 쓸 여유가 남지 않습니다.

진짜 문제는 낭비입니다. 하루 4,320건의 요청 대부분이 동일한 데이터를 돌려줍니다. 코호트 포지셔닝이 매분 바뀌지 않습니다. 청산 리스크 임계값이 수시로 발동되지 않습니다. 레이트 리밋 예산과 서버 부하를 써가며 아무 일도 없었음을 반복 확인하는 셈입니다.

Webhook은 구조 자체를 뒤집습니다

Webhook은 봇과 데이터 소스 사이의 관계를 역전시킵니다. 봇이 타이머에 맞춰 "변한 게 있나요?"라고 묻는 대신, 서버에 URL, 즉 여러분의 엔드포인트를 등록하고 "내가 관심 있는 일이 생기면 이 주소로 POST해줘"라고 말하는 방식입니다. 서버가 감시하고, 봇은 반응합니다.

Hyperliquid 분석에서 webhook을 설정할 법한 이벤트는 실제 트레이딩 결정에 영향을 주는 것들입니다.

• 코호트 포지셔닝 전환: Smart Money(전체 손익 +$100K~+$1M 지갑)가 ETH에서 순 숏에서 순 롱으로 전환하는 경우
• 청산 리스크 임계값: 자산별 청산 노출도가 설정한 위험 수준을 넘는 경우
• 펀딩 레이트 극단값: 레이트가 정의한 임계치를 초과해 과밀 포지셔닝을 신호하는 경우
• 대규모 포지션 변화: Whale 또는 Leviathan 코호트가 대규모 포지션을 열거나 닫는 경우

이런 이벤트는 드뭅니다. 매초, 심지어 매분 발생하지 않습니다. 그래서 폴링이 낭비이고 webhook이 자연스러운 선택인 것입니다. 봇은 설정한 조건이 발동되는 정확한 순간까지 유휴 상태를 유지하고(API 호출 제로), POST를 받으면 페이로드를 검증하고 로직을 실행합니다.

Webhook 알림 흐름이 실제로 작동하는 방식

아키텍처는 단순하지만 세부 사항이 중요합니다. 시장 이벤트에서 봇 행동까지의 순서는 다음과 같습니다.

1. 시장 이벤트 발생. Whale 코호트 지갑들(퍼프 자산 $500K~$1M)이 BTC 포지셔닝을 순 숏에서 순 롱으로 집단 전환합니다.
2. HyperTracker가 전환을 감지합니다. 데이터 파이프라인이 다음 갱신 사이클에 코호트 상태 변화를 처리하고 설정된 webhook 규칙과 대조합니다.
3. Webhook이 발동됩니다. 이벤트 유형, 자산, 코호트, 방향, 크기를 담은 JSON 페이로드와 함께 등록된 엔드포인트에 POST 요청이 전달됩니다.
4. 핸들러가 검증하고 행동합니다. HMAC 서명을 확인하고 페이로드를 파싱해 구축해둔 로직을 실행합니다. 포지션 진입, 대시보드 업데이트, 텔레그램 알림 전송, 혹은 세 가지 모두입니다.

핸들러가 해야 할 일

Webhook을 받는 것은 쉬운 부분입니다. 안정적으로 처리하는 것이 대부분의 빌더가 실수하는 지점입니다. 엔드포인트가 해야 할 일은 다음과 같습니다.

• 서명을 검증합니다. 모든 webhook에는 HMAC 서명 헤더가 포함되어야 합니다. 페이로드를 처리하기 전에 공유 시크릿과 대조해 검증합니다. 이 단계를 건너뛰면 엔드포인트 URL을 아는 누구든 가짜 이벤트를 보낼 수 있습니다.
• 빠르게 응답합니다. 몇 초 이내에 200 상태를 반환합니다. 핸들러가 무거운 작업(주문 체결, 모델 실행)을 해야 한다면, 먼저 webhook을 확인 응답한 후 작업 큐를 이용해 비동기로 처리합니다.
• 중복을 처리합니다. 네트워크 문제로 재시도가 발생할 수 있습니다. 같은 이벤트가 봇을 두 번 트리거하지 않도록 멱등성 로직을 포함합니다. 간단한 방법으로는 페이로드를 해시하고 단기 캐시와 비교해 이미 처리한 것은 건너뛰는 방식이 있습니다.
• 모든 것을 기록합니다. Webhook 페이로드는 휘발성입니다. 처리하고 나면 저장하지 않는 한 사라집니다. 디버깅과 백테스팅을 위해 수신된 모든 이벤트를 타임스탬프와 함께 기록합니다.

# 최소한의 webhook 핸들러 (Python / FastAPI)
from fastapi import FastAPI, Request, HTTPException
import hmac, hashlib

app = FastAPI()
WEBHOOK_SECRET = "your_shared_secret"

@app.post("/webhook/alerts")
async def handle_alert(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Signature")

    expected = hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature or "", expected):
        raise HTTPException(status_code=401)

    payload = await request.json()
    # 비동기 처리를 위해 큐에 넣기
    process_alert.delay(payload)
    return {"status": "received"}

폴링이 여전히 올바른 선택인 경우

Webhook이 폴링보다 무조건 낫지는 않습니다. 드문 이벤트에 낭비 없이 반응하는 특정 문제를 해결하지만, 폴링이 더 깔끔한 아키텍처인 시나리오도 있습니다.

주기적인 대시보드 갱신. 몇 분마다 전체 자산의 코호트 포지셔닝을 보여주는 분석 대시보드를 만든다면, 예약 폴링이 수십 개의 webhook 구독을 관리하는 것보다 단순합니다. 일정 간격으로 전체 스냅샷이 필요한 것이고, 그게 REST가 설계된 용도입니다.

과거 데이터 조회. Webhook은 앞을 봅니다. 지금부터 발생하는 일을 알려줍니다. 백테스팅을 위한 과거 코호트 데이터가 필요하다면(HyperTracker는 코인별 코호트 메트릭 최대 4주, 포지션 및 체결 데이터 6개월 이상을 보관), REST 조회를 써야 합니다.

고급 플랜의 단순한 봇. Flow나 Stream 플랜처럼 월 수십만 건의 요청이 포함된 경우, "낭비된 폴링" 비용은 무시할 수준입니다. 5분마다 하나의 엔드포인트를 폴링하는 봇은 월 약 8,640건의 요청을 사용하므로 한도 내에 충분히 들어옵니다. Webhook의 아키텍처 복잡성이 그만한 가치를 못 할 수도 있습니다.

경험칙: 봇이 특정 조건을 기다렸다가 트리거에 반응한다면 webhook을 씁니다. 봇이 넓은 시장 상태의 주기적 스냅샷이 필요하다면 폴링을 씁니다. 많은 프로덕션 시스템은 둘 다 씁니다. 알림에는 webhook, 알림이 발동될 때 컨텍스트 로딩에는 REST입니다.

HyperTracker에서 전달 방식 선택하기

HyperTracker는 가격 등급에 따라 세 가지 전달 방식을 제공하며, 올바른 선택은 무엇을 만드는지와 아키텍처가 얼마나 이벤트 기반인지에 달려 있습니다.

REST (전 플랜). Free부터 Stream까지 모든 등급에 REST 액세스가 포함됩니다. 이제 막 시작하는 빌더에게는 REST 폴링이 푸시 기반 인프라에 투자하기 전에 트레이딩 전략을 프로토타입하고 검증하는 가장 빠른 방법입니다.

Webhook (Flow 및 Stream). Flow 등급($799/월, 월 40만 건, 분당 200건 레이트 리밋)부터 이용 가능합니다. 알림 기반 봇에 최적인 선택지입니다. 감시할 이벤트를 설정하고 엔드포인트를 등록하면 서버가 모니터링을 담당합니다. 레이트 리밋 예산은 온디맨드 조회를 위해 온전히 남겨둘 수 있습니다.

WebSocket (Stream 전용). Stream 등급($1,999/월)은 지속적인 데이터 피드를 위한 영구 WebSocket 연결을 추가합니다. 기관 데이터 파이프라인, 다중 자산 모니터링 대시보드, 여러 종목에 걸쳐 지속적인 업데이트 스트림이 필요한 상황을 위해 설계되었습니다.

하이브리드 아키텍처

가장 견고한 프로덕션 구성은 전달 방식을 조합합니다. Flow 플랜에서 Hyperliquid 트레이딩 봇의 일반적인 패턴은 다음과 같습니다.

1. Webhook이 코호트 포지셔닝 전환과 청산 리스크 임계값 초과를 감시합니다. 발동되면 봇이 깨어납니다.
2. REST 호출이 webhook이 트리거될 때 컨텍스트를 로드합니다. 봇이 현재 포지션, 최근 체결, 광범위한 시장 메트릭을 조회해 정보에 기반한 결정을 내립니다.
3. REST 폴링이 느린 주기(15분마다)로 실행되어 일반 시장 상태의 로컬 캐시를 유지합니다. 이 캐시 덕분에 webhook이 트리거될 때 컨텍스트가 이미 로드되어 있어 결정이 빨라집니다.

이 하이브리드 모델은 레이트 리밋 사용을 효율적으로 유지합니다. 느린 폴링은 최소한의 요청만 사용하고, webhook은 서버가 밀어주므로 요청이 제로이며, 알림 발동 시의 REST 호출 급증은 목표가 분명하고 짧습니다.

흔한 Webhook 실수(와 예방법)

엔드포인트가 다운되는 경우

webhook이 발동될 때 서버가 응답하지 않으면 이벤트를 놓칩니다. 폴링과 달리(다음 사이클에 다시 시도하면 됨) 놓친 webhook은 제공업체가 재시도하지 않는 한 사라집니다. 이중화를 구축하세요. 업타임이 보장된 클라우드 공급자에서 핸들러를 실행하고, 나중에 재실행할 수 있도록 실패한 전달을 위한 데드 레터 큐를 구현합니다.

서명 검증 무시

서명 검증 없이 노출된 webhook URL은 열린 문이나 다름없습니다. 엔드포인트 URL을 알아낸 누구든 가짜 이벤트를 POST해 봇을 트리거할 수 있습니다. 페이로드를 처리하기 전에 항상 공유 시크릿과 대조해 HMAC 서명을 검증합니다. 실제 자금으로 거래하는 봇에서 이것은 타협할 수 없는 원칙입니다.

핸들러 블로킹

webhook 핸들러가 동기 방식으로 주문을 체결하느라 30초 동안 응답하지 않으면 전달 시스템이 타임아웃되고 재시도해 중복 행동을 유발할 수 있습니다. webhook을 즉시 확인 응답하고(200 반환), 비동기로 처리합니다. BullMQ, Celery, 또는 단순한 Redis 리스트 같은 작업 큐가 이 문제를 깔끔하게 해결합니다.

모니터링 부재

Webhook은 잘 작동할 때도, 작동하지 않을 때도 눈에 보이지 않습니다. 모니터링 없이는 전달이 조용히 멈춰도 알 수가 없습니다. 하트비트를 설정하세요. 설정 가능한 시간 창(예: 활발한 시장 시간대에 몇 시간) 동안 webhook이 발동되지 않으면 내부 알림을 트리거해 조사합니다. 수신된 모든 이벤트를 기록하고 예상 전달 빈도와 주기적으로 비교합니다.

Hyperliquid 데이터 기반 이벤트 중심 알림 구축하기

HyperTracker의 Flow 및 Stream 플랜은 코호트 전환, 청산 리스크, 펀딩 극단값을 엔드포인트에 직접 전달합니다. 지갑 규모와 전체 손익으로 분류된 16개의 행동 코호트. Webhook 하나가 발동되면 봇이 반응합니다.

HyperTracker 플랜 살펴보기

정리: 의사결정 프레임워크

Hyperliquid에서 개발하면서 폴링과 webhook 사이에서 고민 중이라면, 답은 거의 항상 "다른 목적으로 둘 다"입니다. 봇이 소비하는 각 데이터 피드에 대한 결정을 정리하기 위한 간단한 프레임워크입니다.

| 질문 | 해당하면 | | --- | --- | | 봇이 특정 이벤트(코호트 전환, 청산 리스크 급등)에 반응하나요? | Webhook | | 봇이 주기적인 전체 시장 스냅샷이 필요한가요? | 느린 간격으로 REST 폴링 | | 봇이 백테스팅을 위한 과거 데이터가 필요한가요? | REST 조회(일회성 또는 배치) | | 봇이 여러 자산을 병렬로 지속 모니터링하나요? | WebSocket (Stream 등급인 경우) | | 봇이 프로토타입 또는 MVP 단계인가요? | REST 폴링으로 시작, 나중에 webhook으로 전환 |

데이터를 가장 잘 활용하는 빌더들은 webhook으로 언제 볼지 알고, REST로 무엇을 보고 있는지 파악합니다. Webhook은 "Smart Money가 ETH에서 방금 롱으로 전환했어"라고 알려줍니다. REST 호출은 전환 규모가 얼마나 큰지, 다른 코호트는 어떻게 움직이는지, 청산 리스크가 그 움직임을 뒷받침하는지 알려줍니다.

그 조합이 원시 데이터를 의사결정 파이프라인으로 바꿉니다. 봇이 하루에도 수천 번 "새로운 거 있어?"라고 묻는 데 사이클을 낭비하지 않습니다. 기다리다가, 신호를 받고, 완전한 컨텍스트를 갖고 행동합니다. 그것이 만들 가치가 있는 아키텍처입니다.