# 选择 Webhook、WebSocket 或 RPC 轮询

> 原文地址: https://docs.blockvectra.com/zh/guides/webhook-vs-websocket/

向 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 计费](https://docs.blockvectra.com/zh/guides/webhook-push/#计费与示例) | 建连与心跳免费；`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](https://docs.blockvectra.com/zh/guides/webhook-push/)：

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

在对外提供生产接收端前，请仔细核对[原始正文验签与重放流程](https://docs.blockvectra.com/zh/guides/webhook-push/#签名校验)。

## 何时选择 WebSocket 订阅

当应用对事件到达延迟极其敏感，且客户端进程能够维持出站 TCP 长连接时，选用 [WebSocket 订阅](https://docs.blockvectra.com/zh/guides/websocket-subscriptions/)：

* **实时区块头推送**：在网络产生新区块时立即接收 `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`](https://docs.blockvectra.com/zh/errors/#unknown_chain)）。
* **断线重连纪律**：WebSocket 通知在断线期间不会保留在服务端队列。连接中断后客户端必须以随机化指数退避重新建连，并使用 `eth_getLogs` 扫描补全缺失区间。

关于连接限制（每 key 上限 20 连接、每账户上限 50 连接）与过滤器上限，请参阅 [WebSocket 订阅使用指南](https://docs.blockvectra.com/zh/guides/websocket-subscriptions/)。

## 何时选择有界 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`](https://docs.blockvectra.com/zh/errors/#logs_range_too_large)）。宽区间需拆分为不超过 1,000 块的连续分段分别查询。

分段扫描与游标维护算法请参阅 [HyperEVM 日志回补指南](https://docs.blockvectra.com/zh/guides/hyperevm-backfill/) 与 [eth\_getLogs 区块范围限制指南](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)。

完整的工作负载清单与自测方法见[如何选择 RPC 服务商](https://docs.blockvectra.com/zh/guides/choose-rpc-provider/)。

为低量轮询选服务商时，可[对比服务商的常规 RPC 计费与覆盖](https://docs.blockvectra.com/zh/guides/quicknode-alternative/)。比较按量计费与试用、订阅费用；通知和回填的成本计量不同于 RPC 读取。

## 接入指南

### Robinhood Chain 上的 WebSocket

需要 Robinhood Chain 上的实时 `newHeads` 或过滤后的 `logs` 时，按 [WebSocket 订阅指南](https://docs.blockvectra.com/zh/guides/websocket-subscriptions/)完成鉴权与订阅请求。断线后退避重连、重新订阅，并从保存的游标使用 `eth_getLogs` 回补缺失区块；日志按 `(blockHash, transactionHash, logIndex)` 去重。

### HyperEVM 上的有界轮询

需要 HyperEVM（`hyperevm_mainnet`）上的有界轮询与恢复时，按 [HyperEVM 日志回补指南](https://docs.blockvectra.com/zh/guides/hyperevm-backfill/)接入。从保存的游标按 `max_logs_block_range` 分段查询，每段成功处理后将事件与进度一并持久化，失败时重试未完成区段。检查链连续性并回扫重叠区间以处理重组。

## 下一步

* [浏览数据集目录](https://blockvectra.com/zh/data/)，查看 BlockVectra 索引的全部数据集。
* [查看免费额度与定价](https://blockvectra.com/zh/pricing/#free)，确认账户可用的方案。
* [登录控制台](https://console.blockvectra.com/login/?next=%2Fkeys%2F)创建 API key。