Webhook, WebSocket 또는 RPC 폴링 선택
지원 체인, 복구 메커니즘, 수신 엔드포인트 요구사항 및 과금 모델별로 주소 알림, 소켓 구독 및 유한 폴링을 비교합니다.
HTTPS 수신 엔드포인트로 전달받으려면 주소 Webhook을 사용하고, 지원되는 실시간 구독에는 WebSocket을 사용하며, 워크플로에 자체 커서와 복구 기능이 필요한 경우에는 유한(bounded) 폴링을 사용하세요.
개발자와 AI 에이전트를 위한 온체인 이벤트 리스너를 구축할 때는 애플리케이션 아키텍처를 네트워크 지원 역량, 전달 보장 수준, 수신 측 제약 사항 및 운영 비용에 일치시켜야 합니다.
의사결정 매트릭스
아래 표는 지원 네트워크 역량, 인프라 요구사항, 복구 전략 및 과금 모델에 걸쳐 세 가지 연동 메커니즘을 비교합니다:
| 구분 | 주소 Webhook | WebSocket 구독 | 유한 RPC 폴링 |
|---|---|---|---|
| 주요 메커니즘 | 공개 엔드포인트로 HTTPS POST를 통해 전달되는 푸시 알림 | 영구 TLS 연결(wss://)을 통한 풀 스트림(pull-stream) 구독 | 클라이언트가 시작하는 HTTP JSON-RPC 배치 또는 스케줄링된 쿼리 |
| 체인 가용성 | GET /v1/push/chains에 선언된 9개 지원 네트워크 전체 | Robinhood Chain(robinhood_mainnet 및 robinhood_testnet)에서 지원; 미지원 네트워크는 ws: false이며 HTTP 404 반환 | 키 없는 공개 RPC 또는 인증된 JSON-RPC를 통한 9개 지원 네트워크 전체 |
| 수신 측 요구사항 | 공개 접근 가능한 HTTPS URL, 유효한 TLS 인증서, 타임아웃 내 2xx 응답, 원본 본문 HMAC SHA-256 서명 검증 | 아웃바운드 TCP/TLS 클라이언트 연결(wss://); ping/pong 하트비트 및 재연결 백오프 처리 | 상태 비저장 HTTP 클라이언트 또는 스케줄링된 워커; 로컬 블록 커서 저장 |
| 전달 및 순서 보장 | 지수 재시도 백오프가 적용된 최소 1회 전달(at-least-once); 수신 측에서 이벤트 id 또는 구독 간 ref + type 기준으로 중복 제거 필요 | 단일 활성 소켓에서 엄격한 순서 프레임 전달; 연결 해제 중에는 알림 누락 | 확정된 블록 높이에 대한 결정론적 풀 응답; 클라이언트가 실행 속도 조절 |
| 체인 재구성(reorg) | chain.reorg 제어 알림 발생; 수신 측은 정식(canonical) 리플레이를 적용하기 전에 대체된 이벤트를 폐기 | 재구성된 로그 알림에 "removed": true 포함; newHeads는 부모 해시 검사 필요 | 클라이언트가 폴링 틱 간에 parentHash 체인 연속성을 추적하여 리오그 감지 |
| 장애 복구 | 서버 보존 윈도우를 통해 POST /v1/push/subscriptions/{id}/replay로 리플레이 가능; 활성화 블록 이전의 갭은 eth_getLogs 백필 필요 | 서버 측 큐 없음; 클라이언트가 재연결 후 (blockHash, transactionHash, logIndex) 기준으로 중복 제거하며 eth_getLogs로 누락 구간 백필 | 저장된 last_synced_block부터 쿼리 재개; 네트워크의 max_logs_block_range(1,000개 블록) 단위로 청크 분할 |
| 과금 모델 | UTC 일자 동안 온라인 상태인 최대 주소 수 기준 그룹별 일일 주소 수수료 + 전달된 데이터 이벤트에 대한 CU; Webhook 과금 참조 | 핸드셰이크 및 하트비트는 과금되지 않음; eth_subscribe / eth_unsubscribe 및 소켓으로 플러시된 알림 단위에 대해 CU 과금 | Compute Unit 기준으로 요청당 측정: eth_blockNumber(1 CU), eth_call(15 CU), eth_getLogs(30 CU); 1달러당 10M CU |
| 적합한 사용처 | 사용자 입금 모니터링, 핫월렛 주소 추적, 가맹점 결제, 비동기 이벤트 Webhook | 실시간 newHeads 및 필터링된 logs, 반응형 봇, 지원 네트워크의 대화형 UI | 배치 대사, cron 작업, ETL 파이프라인, WebSocket을 지원하지 않는 체인(HyperEVM 등) |
주소 Webhook을 선택해야 하는 경우
백엔드가 인바운드 HTTPS 요청을 수신할 수 있는 표준 웹 서비스로 실행되는 경우 블록체인 Webhook API를 선택하세요:
- 대규모 주소 목록: 지갑별로 영구 소켓을 유지하지 않고도 수천 개의 고객 주소에서 발생하는 입출금을 모니터링할 수 있습니다.
- 서버리스 또는 컨테이너 기반 수신 엔드포인트: 서버리스 함수(AWS Lambda, Cloudflare Workers 등)는 인바운드 webhook 요청 시 즉시 실행되므로 지속적인 연결을 유지할 필요가 없습니다.
- 자동 재시도 및 리플레이: 수신 측의 일시적인 장애는 자동 재시도 백오프로 완화됩니다. 서버 보존 윈도우 내에서는 리플레이 엔드포인트를 사용하여 누락된 전달 건을 다시 전송받을 수 있습니다.
- 활성화 경계 고려사항: 매칭은 구독 변경 사항이 적용된 후(
applied_from_block)부터 시작됩니다. 주소가 추가되기 전이나 구독이offline상태인 동안 발생한 이벤트는 과거 RPC 로그를 통해 조회해야 합니다.
프로덕션 환경의 webhook 수신 엔드포인트를 외부에 노출하기 전에 서명 검증 및 리플레이 워크플로를 검토하세요.
WebSocket 구독을 선택해야 하는 경우
낮은 지연 시간이 필요하고 프로세스가 장기 실행되는 아웃바운드 소켓을 유지할 수 있는 경우 WebSocket 구독을 선택하세요:
- 실시간 블록 헤더: 각 블록이 체인 헤드에 추가될 때
newHeads를 스트리밍합니다. - 컨트랙트 이벤트 필터: 주소 또는 특정
topic0과 일치하는 실시간 컨트랙트logs를 스트리밍합니다. - 프라이빗 환경: 인바운드 공개 HTTPS 포트를 열 수 없는 NAT나 방화벽 뒤의 로컬 스크립트, CLI 에이전트 또는 백엔드 서비스에 적합합니다.
- 네트워크 가용성 확인: WebSocket은 Robinhood Chain(네트워크 식별자
robinhood_mainnet, Chain ID 4663 및robinhood_testnet)에서 지원됩니다. HyperEVM은 현재 WebSocket을 지원하지 않으며(ws: false), 지원되지 않는 체인에 WebSocket 연결을 시도하면 HTTP 404(unknown_chain)가 반환됩니다. - 연결 해제 처리 규율: WebSocket 알림은 연결 해제 시 서버에 보존되지 않습니다. 소켓 연결이 끊어지면 클라이언트는 무작위 지수 백오프로 재연결하고
eth_getLogs를 통해 누락된 블록을 백필해야 합니다.
필터 한도, 연결 상한(키당 20개, 계정당 50개) 및 viem 연결 예제는 WebSocket 구독 가이드를 검토하세요.
유한 RPC 폴링을 선택해야 하는 경우
스케줄링된 워커나 데이터 파이프라인을 실행하거나 WebSocket을 사용할 수 없는 네트워크에서 작업할 때는 유한 JSON-RPC 폴링을 선택하세요:
- WebSocket이 없는 네트워크: HyperEVM(
hyperevm_mainnet)은 현재 JSON-RPC HTTP 접근을 제공하지만 WebSocket은 지원하지 않습니다(ws: false).eth_blockNumber를 폴링하고 지원되는 블록 범위 내에서eth_getLogs를 쿼리하여 HyperEVM 이벤트를 처리할 수 있습니다. - 제어된 쿼리 속도: 폴링을 사용하면 개발자와 AI 에이전트가 요청 빈도를 제어하고, 속도 제한(무료 계정 기본 키당 400 CU/s)에 맞춰 Compute Unit 소비를 관리하며, 장기 실행 작업 중 소켓 끊김을 방지할 수 있습니다.
- 블록 범위 제한: 인증된
eth_getLogs쿼리는 네트워크의max_logs_block_range(1,000개 블록)로 제한됩니다. 이 제한을 초과하면 오류 코드-32602(logs_range_too_large)가 반환됩니다. 더 넓은 구간은 1,000개 블록을 초과하지 않는 연속 청크로 분할하세요.
청킹 알고리즘에 대해서는 HyperEVM 로그 백필 가이드 및 eth_getLogs 블록 범위 가이드를 참조하세요.
전체 워크로드 체크리스트와 자체 테스트 방법은 RPC 제공업체 선택 방법에서 시작하세요.
소규모 폴링을 위해 제공업체를 선택할 때는 표준 RPC 청구 및 지원 범위에 대한 제공업체 비교를 참조하세요. 사용량 기반 청구와 평가판 및 구독 비용을 비교하세요. 알림 및 백필 비용은 RPC 조회와 다른 과금 단위를 사용합니다.
연동 가이드
Robinhood Chain에서의 WebSocket
Robinhood Chain에서의 실시간 newHeads 또는 필터링된 logs는 WebSocket 구독 가이드를 따라 인증 및 구독 요청을 진행하세요. 연결이 끊어지면 백오프로 재연결하고, 다시 구독하며, 저장된 커서로부터 eth_getLogs를 사용하여 누락된 블록을 백필합니다. 로그는 (blockHash, transactionHash, logIndex) 기준으로 중복을 제거하세요.
HyperEVM에서의 유한 폴링
HyperEVM(hyperevm_mainnet)의 경우 HyperEVM 로그 백필 가이드를 따라 유한 폴링 및 복구를 수행하세요. max_logs_block_range 이내의 청크 단위로 저장된 커서부터 쿼리하고, 처리가 성공하면 이벤트와 진행 상태를 함께 영구 저장하며, 불완전한 구간은 재시도합니다. 체인 연속성을 확인하고 중첩 구간을 스캔하여 리오그를 처리하세요.
다음 단계
- 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
- 무료 플랜 및 요금 확인: 계정에 포함된 혜택 확인.
- 콘솔 로그인: API key 생성.
최종 수정일: