quicknode-webhooks-events

用途：本技能用于为 QuickNode 事件投递构建接收端。需先决定使用 Webhooks（模板驱动通知）还是 Streams（可编程、支持历史数据与多目的地管道），两者都要求真实性校验、快速确认、幂等和明确的链重组处理。前提包括选定产品、链、网络、数据集和起始范围，准备 HTTPS 接收端或经批准的持久目的地，以及密钥存储、队列和可重放的事件标识。鉴权：用生成的安全令牌做 HMAC 校验，必须在解析前对未经修改的原始请求字节验签；Streams 在需要其信任模型时加 mTLS。端点令牌与 Admin API 密钥不要放进接收端配置，它们认证的是不同的 QuickNode 表面。步骤：确认过滤、回填、批处理、目的地和重组需求；定义真实性校验；限制接收端，包括限制请求体大小、按配置解 gzip、验证内容类型、解析前校验真实性、持久入队并在超时内返回 2xx；从产品元数据加链、区块哈希、交易或日志位置和目的地派生稳定幂等键，确认前先持久化接收记录，多个日志时不能只用交易哈希去重；按至少一次投递处理重试与暂停，Streams 顺序处理批次、按配置重试并在达到最大失败数后可暂停，多目的地可能向已成功者重放；配置并测试重组行为，使下游状态可逆或带版本，并保留可从已记录区块重放的游标。限制与错误处理：签名失败须在解析前拒绝并仅保留脱敏元数据；接收端超时需把工作移到持久确认边界之后；Streams 暂停需先修复失败目的地再从记录游标重放；重组使事件失效时按区块标识应用补偿状态变更。不要在无明确检查点的情况下创建或修改生产 Stream 或 Webhook。