选择 Webhook、WebSocket 或 RPC 轮询
按链支持、恢复方式、接收端条件与计费比较地址通知、连接订阅和有界轮询。
向 HTTPS 接收端投递可选地址 Webhook，支持的实时订阅可用 WebSocket，需要自己维护游标和恢复时采用有界轮询。
面向开发者与 AI Agent 构建链上事件监听流程时，选择合适的技术方案取决于网络支持能力、投递保证、接收端基础设施与调用成本。
决策对比表
下表从链支持、接收端要求、重组与故障恢复、计费模型等维度对比三种接入方式：
| 维度 | 地址 Webhook | WebSocket 订阅 | 有界 RPC 轮询 |
|---|---|---|---|
| 接入机制 | 通过 HTTPS POST 向公共服务端点投递推送通知 | 基于 TLS 的长连接（wss://）流式订阅 | 客户端自主发起的 HTTP JSON-RPC 批量或定时查询 |
| 链支持 | 在 GET /v1/push/chains 中声明的全部 9 个受支持网络 | 在 Robinhood Chain 上支持（robinhood_mainnet 与 robinhood_testnet）；未支持网络 ws: false 并返回 HTTP 404 | 全部 9 个受支持网络均支持免 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 游标继续查询；按网络 max_logs_block_range（1,000 块）切片请求 |
| 计费模型 | 按组独立收取地址日费与已送达数据事件 CU；地址日费按组在 UTC 日内在线期间的最大地址数计算，详见 Webhook 计费 | 建连与心跳免费；eth_subscribe / eth_unsubscribe 与成功冲刷至套接字发送缓冲区的通知帧按 CU 计费 | 按请求以 Compute Units 计量：eth_blockNumber（1 CU）、eth_call（15 CU）、eth_getLogs（30 CU）；每美元 10,000,000 CU |
| 适用场景 | 用户充值监控、热钱包地址跟踪、商户收款通知、异步事件分发 | 实时 newHeads 与过滤后的 logs、即时响应机器人、支持网络上的交互式界面 | 离线对账、定时脚本、ETL 数据同步、不支持 WebSocket 的网络（如 HyperEVM） |
何时选择地址 Webhook
当业务后端作为可接收外部 HTTPS 请求的常规 Web 服务运行时，优先使用区块链 Webhook API：
- 大规模地址监控：跟踪数千甚至更多用户充值或提现地址的变动，无需为每个地址维护长连接。
- 无状态与 Serverless 接收端：云函数或容器化服务（如 AWS Lambda、Cloudflare Workers）可在收到通知时按需启动，避免空闲常驻连接成本。
- 自动重试与已匹配重放：接收端偶发离线或报错时享受自动指数退避重试；在服务端数据保留窗口内，还可通过重放接口补投历史已匹配事件。
- 生效边界说明：事件匹配仅从地址变更生效的区块（
applied_from_block）开始；地址添加前或订阅处于offline期间的历史事件需通过 RPC 日志回补。
在对外提供生产接收端前，请仔细核对原始正文验签与重放流程。
何时选择 WebSocket 订阅
当应用对事件到达延迟极其敏感，且客户端进程能够维持出站 TCP 长连接时，选用 WebSocket 订阅：
- 实时区块头推送：在网络产生新区块时立即接收
newHeads。 - 合约日志流：根据合约地址或指定
topic0实时接收符合过滤条件的logs。 - 私网或受限环境：适合跑在 NAT 或防火墙后、无法对外暴露公网 HTTPS 端口的本地脚本、命令行 Agent 或内部服务。
- 网络支持确认：WebSocket 在 Robinhood Chain 上支持（网络 slug 为 robinhood_mainnet，Chain ID 4663，以及 robinhood_testnet）。HyperEVM 目前无 WebSocket 支持（
ws: false）；向未支持网络发起 WebSocket 连接将返回 HTTP 404（unknown_chain）。 - 断线重连纪律：WebSocket 通知在断线期间不会保留在服务端队列。连接中断后客户端必须以随机化指数退避重新建连，并使用
eth_getLogs扫描补全缺失区间。
关于连接限制（每 key 上限 20 连接、每账户上限 50 连接）与过滤器上限，请参阅 WebSocket 订阅使用指南。
何时选择有界 RPC 轮询
当运行定时对账任务、数据离线导入流水线，或在未支持 WebSocket 的网络上运行时，选用有界 JSON-RPC 轮询：
- 无 WebSocket 支持的网络：HyperEVM（
hyperevm_mainnet）目前提供 JSON-RPC HTTP 访问，但无 WebSocket 支持（ws: false）。在 HyperEVM 上通过有界轮询eth_blockNumber并调用eth_getLogs可用于获取事件。 - 精确控制查询节奏：轮询允许开发者与 AI Agent 自主调节调用频次，管理 Compute Unit 消耗并遵守速率限额（免费账户默认每 key 400 CU/s），避免长时间长连接带来的意外断开。
- 区块区间跨度限制：认证
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 分段查询，每段成功处理后将事件与进度一并持久化，失败时重试未完成区段。检查链连续性并回扫重叠区间以处理重组。
下一步
最后更新：