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 supported networks declared in GET /v1/push/chains | Networks with ws: true in GET /v1/chains; subscription types are listed in subscriptions | All supported networks in GET /v1/chains 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 from GET /v1/chains |
| 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, eth_call, eth_getLogs; method weights and CU per $1 from GET /v1/plans, shown below |
| 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 |
Active Conversion Parameters
1 USD = 10,000 billing units, 1 billing unit = 1,000 CU (1 USD = 10,000,000 CU).
Formula: CU weight × 1,000,000 ÷ (10,000 × 1,000) USD.
| Method | CU per call | Price per 1M calls (USD) |
|---|---|---|
eth_blockNumber | 1 | $0.10 |
eth_call | 15 | $1.50 |
eth_getLogs | 30 | $3.00 |
debug_traceTransaction | 100 | $10.00 |
data.block | 5 | $0.50 |
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: Check the target network's
wsandsubscriptionsfields in GET /v1/chains. HyperEVM can also use WebSocket; availability is always determined by that catalog. If a network does not serve WebSocket, the connection 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:
- Scheduled and backfill processing: HyperEVM (
hyperevm_mainnet) can continue to use HTTPeth_blockNumberandeth_getLogsfor bounded polling and historical backfill; this does not mean WebSocket is unavailable. - Controlled query pacing: Polling allows developers and AI agents to govern request frequency, manage Compute Unit consumption against per-key rate limits, and avoid socket drops during long-running tasks. Per-key limits — defaults are 100 CU/s and burst 400 CU; after a paid top-up each key is at least 2,000 CU/s and burst 10,000 CU, and higher custom limits are kept.
- Block range limits: Authenticated
eth_getLogsqueries are capped by the network'smax_logs_block_rangefrom GET /v1/chains. Exceeding this limit returns error code-32602(logs_range_too_large). Split wider intervals into consecutive chunks not exceeding the target network'smax_logs_block_range.
| Chain | Chain slug | max_logs_block_range (blocks) |
|---|---|---|
| Arbitrum One | arb_mainnet | 1,000 |
| Arc | arc_mainnet | 1,000 |
| Avalanche C-Chain | avax_mainnet | 1,000 |
| Base | base_mainnet | 1,000 |
| Berachain | berachain_mainnet | 1,000 |
| Boba | boba_mainnet | 1,000 |
| BNB Smart Chain | bsc_mainnet | 1,000 |
| Celo | celo_mainnet | 1,000 |
| Ethereum | eth_mainnet | 1,000 |
| Ethereum Sepolia | eth_sepolia | 1,000 |
| Fraxtal | fraxtal_mainnet | 1,000 |
| Gnosis | gnosis_mainnet | 1,000 |
| HyperEVM | hyperevm_mainnet | 1,000 |
| Ink | ink_mainnet | 1,000 |
| Katana | katana_mainnet | 1,000 |
| Linea | linea_mainnet | 1,000 |
| Metal L2 | metall2_mainnet | 1,000 |
| Mode | mode_mainnet | 1,000 |
| OP Mainnet | op_mainnet | 1,000 |
| Polygon | polygon_mainnet | 1,000 |
| Robinhood Chain | robinhood_mainnet | 1,000 |
| Robinhood Chain Testnet | robinhood_testnet | 1,000 |
| Rootstock | rootstock_mainnet | 1,000 |
| Soneium | soneium_mainnet | 1,000 |
| Sonic | sonic_mainnet | 1,000 |
| Unichain | unichain_mainnet | 1,000 |
| World Chain | world_mainnet | 1,000 |
| X Layer | xlayer_mainnet | 1,000 |
| Zora | zora_mainnet | 1,000 |
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: