选择 Webhook、WebSocket 或 RPC 轮询

对比地址 Webhook、WebSocket 订阅与有界 RPC 轮询:推送按事件 id 去重,长连接断线期间不保留通知,轮询从游标按各链区块上限分段调用日志接口;按链支持、接收端条件、重组恢复与计费选择。

向 HTTPS 接收端投递可选地址 Webhook,支持的实时订阅可用 WebSocket,需要自己维护游标和恢复时采用有界轮询。

面向开发者与 AI Agent 构建链上事件监听流程时,选择合适的技术方案取决于网络支持能力、投递保证、接收端基础设施与调用成本。

决策对比表

下表从链支持、接收端要求、重组与故障恢复、计费模型等维度对比三种接入方式:

维度地址 WebhookWebSocket 订阅有界 RPC 轮询
接入机制通过 HTTPS POST 向公共服务端点投递推送通知基于 TLS 的长连接(wss://)流式订阅客户端自主发起的 HTTP JSON-RPC 批量或定时查询
链支持在 GET /v1/push/chains 中声明的全部受支持网络GET /v1/chains 中 ws: true 的网络;订阅类型取 subscriptionsGET /v1/chains 中的全部受支持网络均支持免 key 公共 RPC 或认证 JSON-RPC
接收端要求公网可访问的 HTTPS URL、有效 TLS 证书、超时时间内返回 2xx 响应、原始正文 HMAC SHA-256 签名校验出站 TCP/TLS 客户端长连接(wss://);需处理心跳(ping/pong)与重连退避无状态 HTTP 客户端或定时任务;需自行保存本地区块游标
投递与保序至少投递一次(At-least-once)并带指数退避重试;接收端需按事件 id 去重,跨订阅按 ref + type 去重单条活动长连接内严格保序;连接断开期间服务端不保留离线消息针对已确认区块高度的确定性拉取;客户端完全自主控制查询节奏
链重组处理发送 chain.reorg 控制通知;接收端先标记或丢弃被替换的旧事件,再保留重投的规范链事件日志通知携带 "removed": true 标识被重组移除的日志;newHeads 需比对父区块哈希客户端在轮询间隔中检查 parentHash 链式连续性以检测重组
故障与断线恢复在服务端保留窗口内可通过 POST /v1/push/subscriptions/{id}/replay 重放已匹配事件;生效前历史需用 eth_getLogs 回补服务端不保留跨连接队列;客户端重连后需基于 eth_getLogs 与 (blockHash, transactionHash, logIndex) 三元组去重回补从保存的 last_synced_block 游标继续查询;按 GET /v1/chains 中各网络的 max_logs_block_range 切片请求
计费模型按组独立收取地址日费与已送达数据事件 CU;地址日费按组在 UTC 日内在线期间的最大地址数计算,详见 Webhook 计费建连与心跳免费;eth_subscribe / eth_unsubscribe 与成功冲刷至套接字发送缓冲区的通知帧按 CU 计费按请求以 Compute Units 计量:eth_blockNumber、eth_call、eth_getLogs;方法权重与每美元 CU 取自 GET /v1/plans,见下表
适用场景用户充值监控、热钱包地址跟踪、商户收款通知、异步事件分发实时 newHeads 与过滤后的 logs、即时响应机器人、支持网络上的交互式界面离线对账、定时脚本、ETL 数据同步

当前换算基准参数

1 USD = 10,000 计费单位,1 计费单位 = 1,000 CU(即 1 USD = 10,000,000 CU)。

换算公式:单次调用 CU 权重 × 1,000,000 ÷ (10,000 × 1,000) 美元。

方法单次调用 CU每百万次调用价格(USD)
eth_blockNumber1$0.10
eth_call15$1.50
eth_getLogs30$3.00
debug_traceTransaction100$10.00
data.block5$0.50

何时选择地址 Webhook

当业务后端作为可接收外部 HTTPS 请求的常规 Web 服务运行时,优先使用区块链 Webhook API:

  • 大规模地址监控:跟踪数千甚至更多用户充值或提现地址的变动,无需为每个地址维护长连接。
  • 无状态与 Serverless 接收端:云函数或容器化服务(如 AWS Lambda、Cloudflare Workers)可在收到通知时按需启动,避免空闲常驻连接成本。
  • 自动重试与已匹配重放:接收端偶发离线或报错时享受自动指数退避重试;在服务端数据保留窗口内,还可通过重放接口补投历史已匹配事件。
  • 生效边界说明:事件匹配仅从地址变更生效的区块(applied_from_block)开始;地址添加前或订阅处于 offline 期间的历史事件需通过 RPC 日志回补。

在对外提供生产接收端前,请仔细核对原始正文验签与重放流程。

何时选择 WebSocket 订阅

当应用对事件到达延迟极其敏感,且客户端进程能够维持出站 TCP 长连接时,选用 WebSocket 订阅:

  • 实时区块头推送:在网络产生新区块时立即接收 newHeads。
  • 合约日志流:根据合约地址或指定 topic0 实时接收符合过滤条件的 logs。
  • 私网或受限环境:适合跑在 NAT 或防火墙后、无法对外暴露公网 HTTPS 端口的本地脚本、命令行 Agent 或内部服务。
  • 网络支持确认:在 GET /v1/chains 中查看目标网络的 ws 与 subscriptions。HyperEVM 同样可以选择 WebSocket,可用性始终以该目录为准。网络未提供 WebSocket 时,连接会返回 HTTP 404(unknown_chain)。
  • 断线重连纪律:WebSocket 通知在断线期间不会保留在服务端队列。连接中断后客户端必须以随机化指数退避重新建连,并使用 eth_getLogs 扫描补全缺失区间。

关于连接限制(每 key 上限 20 连接、每账户上限 50 连接)与过滤器上限,请参阅 WebSocket 订阅使用指南。

何时选择有界 RPC 轮询

当运行定时对账任务、数据离线导入流水线,或在未支持 WebSocket 的网络上运行时,选用有界 JSON-RPC 轮询:

  • 定时处理与历史回补:HyperEVM(hyperevm_mainnet)仍可使用 HTTP eth_blockNumber 与 eth_getLogs 做有界轮询和历史回补;这并不表示没有 WebSocket。
  • 精确控制查询节奏:轮询允许开发者与 AI Agent 自主调节调用频次,管理 Compute Unit 消耗并遵守每 key 速率限额,避免长时间长连接带来的意外断开。每 key 限额——默认 100 CU/s、突发 400 CU;付费充值后每个 key 至少 2,000 CU/s、突发 10,000 CU,更高的自定义限额保持不变。
  • 区块区间跨度限制:认证 eth_getLogs 请求的单次区间受限于 GET /v1/chains 中各网络的 max_logs_block_range。请求范围超过该限制将返回错误码 -32602(logs_range_too_large)。宽区间需拆分为不超过目标网络 max_logs_block_range 的连续分段分别查询。
链链标识max_logs_block_range(区块数)
Arbitrum Onearb_mainnet1,000
Arcarc_mainnet1,000
Avalanche C-Chainavax_mainnet1,000
Basebase_mainnet1,000
Berachainberachain_mainnet1,000
Bobaboba_mainnet1,000
BNB Smart Chainbsc_mainnet1,000
Celocelo_mainnet1,000
Ethereumeth_mainnet1,000
Ethereum Sepoliaeth_sepolia1,000
Fraxtalfraxtal_mainnet1,000
Gnosisgnosis_mainnet1,000
HyperEVMhyperevm_mainnet1,000
Inkink_mainnet1,000
Katanakatana_mainnet1,000
Linealinea_mainnet1,000
Metal L2metall2_mainnet1,000
Modemode_mainnet1,000
OP Mainnetop_mainnet1,000
Polygonpolygon_mainnet1,000
Robinhood Chainrobinhood_mainnet1,000
Robinhood Chain Testnetrobinhood_testnet1,000
Rootstockrootstock_mainnet1,000
Soneiumsoneium_mainnet1,000
Sonicsonic_mainnet1,000
Unichainunichain_mainnet1,000
World Chainworld_mainnet1,000
X Layerxlayer_mainnet1,000
Zorazora_mainnet1,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 分段查询,每段成功处理后将事件与进度一并持久化,失败时重试未完成区段。检查链连续性并回扫重叠区间以处理重组。

下一步

最后更新:

本页目录