用途:帮助开发者搭建 Recurly webhook 接收端点,完成签名验证、安全加固、事件解析与分发。
主要能力:验证 recurly-signature 头(JSON 负载使用 HMAC-SHA256,签名消息为 ${timestamp}.${rawBody},原始未解析 body;签名头为毫秒级时间戳加一个或多个逗号分隔的十六进制签名,24 小时密钥轮换期间多签名任一匹配即有效,需常量时间比较)。另支持 HTTP Basic Auth 与 Recurly 公布的 IP 段白名单。提供 express、nextjs、fastapi 示例目录。
使用方式:传统 JSON webhook 以通知类型为唯一顶层键,例如 new_subscription_notification 包裹 account、subscription 等对象;先按键名取类型再分发。可用环境变量 RECURLY_WEBHOOK_SECRET、RECURLY_WEBHOOK_USER、RECURLY_WEBHOOK_PASSWORD、RECURLY_API_KEY 配置。本地调试命令:npx hookdeck-cli listen 3000 recurly --path /webhooks/recurly。
适用场景:新订阅、订阅变更/取消/过期/续订、支付成功/失败、新账户等通知的处理流程。
限制:官方 recurly SDK 是 API 客户端,不提供 webhook 验证助手,需手动实现签名验证;旧版 XML 负载不签名;webhook 可能乱序或重复投递,关键流程应通过 API 确认对象状态并做幂等处理;Recurly 重试采用指数退避,最多 10 次。部分细节暂未提供。