用途:为 Polar、RevenueCat 或任意支付/事件提供方创建可用于生产的 Webhook 处理器,适用于需要接入支付事件、订阅状态同步的场景。
主要能力:提供统一的 5 步处理模式(校验签名、解析事件、幂等检查、处理业务逻辑、始终返回 200);给出 Polar.sh 与 RevenueCat 的签名校验差异(Polar 使用 HMAC-SHA256,RevenueCat 使用 Bearer token);列出需处理的事件(如 subscription.created/updated/cancelled/revoked,INITIAL_PURCHASE/RENEWAL/CANCELLATION/EXPIRATION/BILLING_ISSUE);给出订阅状态与用户体验、DB 状态的对应关系(active、trial、past_due、cancelled、expired)。
使用方式:按模板在 app/api/webhooks/[provider]/route.ts 中实现 POST 处理器,依次执行签名验证、JSON 解析、基于 event.id 或 webhook-id 的幂等检查(示例使用 Upstash Redis,带 24h TTL)、业务处理与标记已处理,最终返回 200;错误时记录到 Sentry 但仍返回 200 以避免重试风暴。必要命令与依赖:@upstash/redis、Sentry;环境变量 WEBHOOK_SECRET、UPSTASH_URL、UPSTASH_TOKEN。
限制与注意:资料未提供具体安装命令、价格、平台支持范围或部署细节,暂未提供。常见错误包括错误时返回 500 导致无限重试、缺少签名校验、缺少幂等导致重复扣费或重复授权、信任前端支付状态、未区分 cancelled 与 expired 等状态。付费状态必须从 Webhook 判断而非前端。