Polygon Webhooks：无需轮询即可获取实时链上事件

Polygon Webhook 是服务在 Polygon 链上发生事件时发送到您服务器的 HTTP 回调，例如 USDC 存款到达您的某个地址。您注册一个 URL，提供方监控链上活动，您的后端便会收到签名过的 POST 请求，而无需每隔几秒就轮询一次 RPC 节点。本指南涵盖其在 Polygon PoS 上的工作原理、可能出现的问题，以及如何构建一个可托付资金的处理器。

TL;DR

• Webhook 替代轮询：提供方监控 Polygon 并将事件（存款、转账、代币移动）推送到您的端点。
• Polygon 出块约每 2 秒一次，因此事件很快，但在入账前仍需确认策略。
• 将每次投递视为可能重复、延迟或乱序：验证签名、存储事件 ID，并幂等处理。
• 快速确认收到，将业务逻辑放入队列，并按计划对账。
• Chaingateway Webhook 提供 HMAC 签名、预解码的 Polygon 事件，让您无需运行节点和解析日志。

目录

• Polygon Webhook 究竟是什么
• 为什么 Webhook 在 Polygon 上优于轮询
• Polygon PoS 的确认、终局性与重组
• 安全的 Polygon Webhook 处理器长什么样
• Polygon 上的代币与边缘情况
• 自建还是使用统一 API
• 我们的观点：Webhook 是账本问题，而非通知问题
• 通过 Chaingateway 获取 Polygon Webhook
• 上线清单
• 常见问题
• 来源

Polygon Webhook 究竟是什么

Polygon PoS 是一条 EVM 链。每笔 ERC-20 转账（无论是 USDC、USDT 还是您自己发行的代币）都会触发 Transfer 日志。原生 POL 以纯价值转移形式移动，完全没有日志。原始 RPC 以不同结构返回两者：代币用日志，原生币用交易与追踪数据。若想知道客户已付款，您必须自行拼凑这幅图景。

Webhook 服务负责拼装。您订阅一个地址（或一组地址），当匹配事件发生时，服务会向您的 URL 发送 JSON 载荷。优质的载荷会告诉您链、交易哈希、发送方、接收方、代币、人类可读单位的金额、区块号以及唯一事件标识符。这就是“这是一条带十六进制主题的日志”与“客户 4812 支付了 250 USDC”的区别。

人们搜索此关键词时真正想找的其实是三种不同工具：

• 地址与支付 Webhook：当资金打入这些地址时通知我。这是支付流所需。
• 合约事件 Webhook：当指定智能合约触发指定事件时通知我。这是 dApp 后端与分析所需。
• 协议层 Webhook：Polygon 官方产品就其自身运营发出的通知。这些属于该产品文档范畴，不属于通用链监听器。

本文聚焦第一种，并对第二种补充说明。

为什么 Webhook 在 Polygon 上优于轮询

根据此确认时间参考，Polygon 约每 2 秒产生一个区块。如果你轮询 RPC 端点获取新区块并自行过滤日志，你将面临一个无解的权衡：

• 每隔几秒轮询一次，你会耗尽速率限制，并为大量空响应付费。
• 每分钟轮询一次，你的客户在付款后将盯着加载动画等待一分钟。
• 重启后错过某个区块范围，你的账本中就会出现静默的空白。

Webhook 扭转了这一局面。提供商负责监控、重试和区块记账。你的工作缩减为运行一个能正确处理事件的端点。我们在 Webhook 对比 WebSocket 一文中更深入地探讨了架构权衡，包括我们推荐的摄入、队列和扇出模式。

Polygon PoS 上的确认、终局性与重组

在首次发现交易时触发的 Webhook 很快，但并非终局。在你发放商品或入账前，请决定等待多少个区块。

Polygon PoS 确认迅速。一款追踪工具显示典型首次确认耗时 1 至 5 秒，并指出交易所通常等待 128 个区块（约 4 至 5 分钟）以防范重组。另一消息来源称 Heimdall v2 升级于 2025 年 7 月将硬终局性缩短至约 5 秒。不同交易所和工具的做法各异，网络升级也会改变数值，因此在生产环境固定阈值前，请查阅最新的 Polygon 文档。

一种切实可行的选择方法是将策略与风险金额挂钩：

此表为我们的建议策略，非 Polygon 规则。请选择符合自身风险承受能力的数值并记录在案。

在数据模型中，为每笔传入付款赋予状态，如 detected（已检测）、confirming（确认中）和 final（已终局）。立即向客户展示首个状态，仅在最后状态时移动资金。若提供商在确认累积时发送单独事件，请加以利用；若无，则存储首个事件的区块号，并通过定时器与链头高度比对。

安全的 Polygon Webhook 处理器长什么样

Polygon 开发者文档包含一份针对其自有产品的接收 Webhook 指南，其中的原则适用于所有 Webhook 集成：验证投递，并在不重复处理、不应用过时状态的前提下应用事件。以下是针对链上事件的同等规范。

1. 在任何其他操作前验证签名

任何找到你 URL 的人都能向其发起 POST 请求。无验证时，攻击者可发送伪造的“收到 250 USDC”并骗走你的产品。对未签名或签名错误的请求返回 401 并拒绝解析正文。

Chaingateway 使用 HMAC 对请求进行签名。您需使用共享密钥对原始请求体计算签名，并采用恒定时间比较进行验证。必须使用原始字节，而非重新序列化的 JSON 对象，因为重新序列化会改变空白字符和键的顺序，导致匹配失败。我们关于增强 Webhook 安全性的新功能的文章详细解释了验证选项。

关于保护密钥、端点以及数字资产周围操作流程的更宏观视角，这篇数字资产安全与风险管理概述是解决非代码层面问题的有用参考。

2. 使处理过程幂等

假设至少投递一次。您端的超时会导致发送方重试，而重试可能在您已处理完第一份副本后到达。为每个事件存储一个唯一键，理想情况下是交易哈希加日志索引，或提供商提供的事件 ID。在数据库上为其设置唯一约束：

INSERT INTO processed_events (event_key, received_at)
VALUES ($1, now())
ON CONFLICT (event_key) DO NOTHING;

如果插入影响零行，说明您已见过此事件。返回 200 并停止。将插入和余额更新放在同一数据库事务中，这样崩溃就不会导致二者只有一个完成。

3. 快速确认，稍后处理

一旦事件通过验证并安全存储，立即返回 2xx。将发送邮件给客户、更新账本、调用其他服务等耗时工作放入队列异步处理。如果您的处理器耗时三十秒，发送方会超时并重试，您将不得不调试重复事件。

4. 不要信任顺序

关于同一笔付款的两个事件可能以任意顺序到达，例如确认更新可能在原始检测之前到达。比较区块号或序列字段，忽略任何比您已持有状态更旧的内容。绝不允许迟到的 “detected” 事件覆盖 “final” 记录。

5. 验证载荷声称的内容

检查接收地址是否为您签发的地址、代币合约是否为您接受的合约、金额是否与发票匹配。这在 Polygon 上比人们预期的更重要，因为任何人都可以部署一个名为 “USDC” 的代币并发送到您的地址。请比较合约地址，切勿比较符号。

6. 为故障做计划

您的服务器迟早会宕机。提前决定如何恢复：

• 使用支持失败重试的提供商。
• 运行对账任务，例如每隔几分钟检查一次您地址的余额或近期转账，标记 Webhook 日志中从未出现的内容。
• 当异常长时间未收到事件时发出警报。在繁忙系统上，沉默本身就是信号。

Webhook 是您的快速通道。对账是您的安全网。两者都要运行。

Polygon 上的代币与边缘情况

USDC 和 USDT。 稳定币支付是开发者设置 Polygon Webhook 的主要原因，因为手续费低、结算快。请务必了解每种稳定币在 Polygon 上使用的合约，并将这些地址加入白名单，如上所述。

原生 POL。 原生转账不产生代币日志，因此仅基于 Transfer 事件构建的监听器会漏掉它们。如果您计划接受 POL，请确认您的提供商也会上报原生币移动。

合约到地址的支付。 支付可能来自智能合约钱包或多签钱包，而非普通账户。不要假设发送方就是客户。请通过您为客户生成的接收地址将支付与客户关联，而非通过发送方。

失败与回滚的交易。 回滚的交易会消耗 Gas 但不会转移任何资产。仅对代表成功转账的事件采取行动。

灰尘与垃圾代币。 未经请求的代币会定期出现在地址中。忽略您未加入白名单的合约。

自己构建还是使用统一 API

获取 Polygon 事件通知有三条现实路径：

1. 运行自己的节点和监听器。 控制力最大，但您需自行负责节点升级、存储增长、日志解码、重组处理和正常运行时间。当链基础设施是您的产品时，此方案合理。
2. 使用通用节点或数据提供商并自行编写过滤逻辑。 运维负担较小，但您仍需构建订阅、重试、解码和签名层。
3. 使用面向支付的 API，获取已解码、已签名的事件。 您只需编写端点和业务逻辑，无需其他工作。

对于希望在产品中接收或发送加密货币的团队，第三条路径通常能最快投入生产。我们在 区块链 API 对比：6 种类型及适用场景 中更深入地对比了这些选项。

我们的观点：Webhook 是账本问题，而非通知问题

我们看到的大多数集成 Bug 并非关于接收 HTTP 请求，而是关于之后发生的事。团队将 Webhook 视为触发器（“支付到账，发货”），而它实际上只是账本的一个输入，该账本必须在重试、重组和重启下保持正确。

这塑造了我们构建 Chaingateway 的方式。我们提供预解码的事件，因此您的代码读取的是金额和代币，而非十六进制编码的日志主题。我们使用 HMAC 对每个请求签名，以便您的端点能拒绝伪造请求。并且我们通过一个 REST API 覆盖 Polygon 以及 Ethereum、Tron、Bitcoin、Solana、BNB Chain 和 Arbitrum，因此当您增加第二条链时，处理逻辑保持不变。

我们的建议：先编写幂等性和对账代码，再处理正常流程。如果您能重放同一事件十次、打乱三个事件的顺序，最终仍得到正确的余额，其余工作就容易了。我们关于 使用 Webhook 自动处理存款 的文章详细演示了该流程。

— Bitblade

通过 Chaingateway 获取 Polygon Webhook

通过 Chaingateway Webhooks，您可以通过 API 创建钱包或注册地址，订阅支付事件，并在您的端点接收签名通知。Polygon API 页面涵盖在 Polygon 上发送和接收 USDC 与 USDT，而 Blockchain API 则涵盖支持链上的钱包、转账、解码交易数据和 Gas 估算。

套餐详情发布在 定价页面：

付费访问在免费试用后开始，因此您可以在承诺之前测试完整流程，包括签名验证和重复处理。

发布前核对清单

在将生产流量指向您的端点之前，请逐项核对：

• 仅限 HTTPS，且持有有效证书。
• 在原始请求体上验证签名，使用恒定时间比较。
• 对事件键设置唯一约束。
• 在几秒内返回 2xx，将耗时工作移至队列。
• 合约地址加入白名单，校验金额和接收方。
• 状态模型包含待处理和最终状态，并有文档化的确认阈值。
• 设置对账任务和缺失事件告警。
• 密钥存储在代码库之外，且可在不停机的情况下轮换。
• 重放测试：在预发布环境多次、乱序发送同一事件。

常见问题

Polygon Webhook 是否也会为原生 POL 触发？

这取决于提供商。代币转账会产生日志，易于追踪；而原生币转账需要交易级监控。在依赖其处理 POL 支付前，请确认您的提供商是否列出原生币事件。

在 Polygon 上应等待多少个确认？

没有统一规则。某些交易所类型的设置会等待 128 个区块，约 4 到 5 分钟，而小额支付通常更早以待处理状态入账。根据风险金额匹配阈值，并结合当前 Polygon 文档重新核对。

事件触发时我的端点宕机了怎么办？

您需要两层保障：一是提供商对失败投递进行重试，二是您自己的对账任务将记录与链上数据比对。两者结合，即使在长时间宕机后也能弥补缺口。

同一个 Webhook 会到达两次吗？

会，请假设它会发生。超时后的重试是常见原因。在数据库中用唯一约束存储事件键，对已处理事件返回 200。

来源

• Polygon 确认时间参考
• 各网络 USDT 确认时间
• Polygon 开发者文档

推荐阅读

• 区块链 Webhook 与事件通知
• 面向开发者的 Webhooks 与 WebSockets：摄入、队列、扇出模式
• 使用 Webhook 自动处理充值