Choose Webhooks, WebSocket or RPC Polling
Compare address notifications, socket subscriptions and bounded polling by chain support, recovery, receiver requirements and billing.
Use address Webhooks for delivery to an HTTPS receiver, WebSocket for supported live subscriptions and bounded polling when the workflow needs its own cursor and recovery.
Building on-chain event listeners for developers and AI agents requires matching application architecture to network capabilities, delivery guarantees, receiver constraints, and operational cost.
Decision matrix
The table below contrasts all three integration mechanisms across supported network capabilities, infrastructure requirements, recovery strategies, and billing models:
| Dimension | Address Webhooks | WebSocket Subscriptions | Bounded RPC Polling |
|---|---|---|---|
| Primary mechanism | Push notification delivered via HTTPS POST to a public endpoint | Pull-stream subscription over persistent TLS connection (wss://) | Client-initiated HTTP JSON-RPC batch or scheduled queries |
| Chain availability | All 9 supported networks declared in GET /v1/push/chains | Supported on Robinhood Chain (robinhood_mainnet and robinhood_testnet); unserved networks have ws: false and return HTTP 404 | All 9 supported networks via keyless public RPC or authenticated JSON-RPC |
| Receiver requirements | Publicly accessible HTTPS URL, valid TLS certificate, 2xx response within timeout, raw-body HMAC SHA-256 signature verification | Outbound TCP/TLS client connection (wss://); handles ping/pong heartbeats and reconnection backoff | Stateless HTTP client or scheduled worker; stores local block cursor |
| Delivery & ordering | At-least-once delivery with exponential retry backoff; receiver must deduplicate by event id, or by ref + type across subscriptions | Strictly ordered frames on a single active socket; notifications dropped during disconnections | Deterministic pull responses for confirmed block heights; client paces execution |
| Chain reorganizations | Control notifications emitted for chain.reorg; receiver discards replaced events before applying canonical replays | Log notifications carry "removed": true for reorged logs; newHeads requires parent hash checking | Client tracks parentHash chain continuity across poll ticks to detect reorgs |
| Failure recovery | Server retention window allows replay via POST /v1/push/subscriptions/{id}/replay; gaps before activation block require eth_getLogs backfill | No server-side queue; client reconnects and backfills missed ranges via eth_getLogs deduplicated by (blockHash, transactionHash, logIndex) | Resumes querying from stored last_synced_block; partitions chunks by network max_logs_block_range (1,000 blocks) |
| Billing model | Per-group daily address fee, based on the largest address count while online during the UTC day, plus CU for delivered data events; see Webhook billing | Handshake and heartbeats unbilled; eth_subscribe / eth_unsubscribe and flushed socket notification units billed in CU | Metered per request in Compute Units: eth_blockNumber (1 CU), eth_call (15 CU), eth_getLogs (30 CU); 10M CU per $1 |
| Best suited for | User deposit monitoring, hot-wallet address tracking, merchant checkouts, asynchronous event webhooks | Live newHeads and filtered logs, reactive bots, interactive UIs on supported networks | Batch reconciliation, cron jobs, ETL pipelines, chains without WebSocket support (such as HyperEVM) |
When to choose address Webhooks
Choose the Blockchain Webhook API when your backend runs as a standard web service capable of receiving inbound HTTPS requests:
- Large address lists: Monitor deposits or withdrawals across thousands of customer addresses without maintaining persistent sockets per wallet.
- Serverless or containerized receivers: Serverless functions (AWS Lambda, Cloudflare Workers) spin up on incoming webhooks and do not need to keep continuous connections alive.
- Automated retries and replay: Transient receiver outages are mitigated by automatic retry backoff. Within the server retention window, missed deliveries can be redelivered using the replay endpoint.
- Activation boundary considerations: Matching begins only after the subscription change is applied (
applied_from_block). Events that occurred before an address was added or while a subscription wasofflinemust be queried via historical RPC logs.
Review signature verification and replay workflows before exposing production webhook receivers.
When to choose WebSocket subscriptions
Choose WebSocket Subscriptions when low latency is required and your process can maintain a long-running outbound socket:
- Live block headers: Stream
newHeadsas each block is appended to the chain head. - Contract event filters: Stream real-time contract
logsmatching an address or specifictopic0. - Private environments: Ideal for local scripts, CLI agents, or backend services behind NAT or firewalls that cannot expose an inbound public HTTPS port.
- Network availability check: WebSocket is supported on Robinhood Chain (network slug
robinhood_mainnet, Chain ID 4663, androbinhood_testnet). HyperEVM currently has no WebSocket support (ws: false); attempting a WebSocket connection to an unserved chain returns HTTP 404 (unknown_chain). - Disconnection discipline: WebSocket notifications are not retained on the server across disconnections. When the socket drops, clients must reconnect with randomized exponential backoff and backfill missed blocks via
eth_getLogs.
Review the WebSocket Subscriptions guide for filter limits, connection caps (20 per key, 50 per account), and viem connection examples.
When to choose bounded RPC polling
Choose bounded JSON-RPC polling when running scheduled workers, data pipelines, or operating on networks where WebSocket is unavailable:
- Networks without WebSocket: HyperEVM (
hyperevm_mainnet) currently provides JSON-RPC HTTP access but no WebSocket (ws: false). Pollingeth_blockNumberand queryingeth_getLogswithin supported block ranges supports HyperEVM event processing. - Controlled query pacing: Polling allows developers and AI agents to govern request frequency, manage Compute Unit consumption against rate limits (400 CU/s per key by default on free accounts), and avoid socket drops during long-running tasks.
- Block range limits: Authenticated
eth_getLogsqueries are capped by the network'smax_logs_block_range(1,000 blocks). Exceeding this limit returns error code-32602(logs_range_too_large). Split wider intervals into consecutive chunks not exceeding 1,000 blocks.
See the HyperEVM log backfill guide and the eth_getLogs block range guide for chunking algorithms.
For a complete workload checklist and self-tests, start with How to choose an RPC provider.
When choosing a provider for low-volume polling, compare providers for standard RPC billing and coverage. Compare usage billing with trial and subscription costs; notification and backfill costs use different meters from RPC reads.
Implementation guides
WebSocket on Robinhood Chain
For live newHeads or filtered logs on Robinhood Chain, follow the WebSocket Subscriptions guide for authentication and subscription requests. After a disconnect, reconnect with backoff, re-subscribe and backfill missed blocks from a saved cursor with eth_getLogs; deduplicate logs by (blockHash, transactionHash, logIndex).
Bounded polling on HyperEVM
For HyperEVM (hyperevm_mainnet), follow the HyperEVM log backfill guide for bounded polling and recovery. Query from the saved cursor in chunks within max_logs_block_range, persist events and progress together after successful processing, and retry incomplete ranges. Check chain continuity and scan overlapping ranges to handle reorgs.
Next steps
- Browse the datasets directory to see every dataset BlockVectra indexes.
- See the free plan and pricing to check what your account includes.
- Log in to the console to create an API key.
Last updated: