dodo-webhook

用途

该技能用于在 Next.js 或 FastAPI 项目中实现 Dodo Payments 的 Webhook 接收与数据库同步，适用于处理支付和订阅事件的场景。

主要能力

• 签名验证：遵循 Standard Webhooks 规范，处理 webhook-id、webhook-timestamp、webhook-signature 三个请求头。
• 事件路由：示例覆盖 payment.succeeded、payment.failed、subscription.active、subscription.cancelled、subscription.on_hold 等事件类型。
• 幂等处理：通过 processed_webhooks 表记录已处理事件，避免重复入账。
• 数据库同步：根据事件更新用户积分、套餐与 dodoCustomerId。
• 栈检测：先识别框架（Next.js App Router / Pages Router / FastAPI / Express）、ORM（Prisma / Drizzle / Supabase / Mongoose / raw SQL）与用户模型字段。

使用方式

1. 安装依赖：Node/Next.js 使用 npm install standardwebhooks，Python/FastAPI 使用 pip install standardwebhooks。
2. 配置环境变量：DODO_API_KEY、DODO_WEBHOOK_SECRET（whsec_... 格式）、DODO_PRODUCT_ID、APP_URL。
3. 创建 Webhook 端点：Next.js App Router 下放置于 app/api/webhooks/dodo/route.ts，FastAPI 下为 /api/webhooks/dodo 路由。端点读取原始请求体（raw body），验证签名后再路由到事件处理器。
4. 代理模式：若前端代理到独立后端，Next.js 需转发原始 body 与三个 Webhook 请求头，且不得解析 body。
5. 幂等层：创建 processed_webhooks 表（webhook_id 为主键），在处理前查询、处理后写入。
6. 创建 Checkout：在创建支付链接时将 userId 写入 metadata，Webhook 依靠该字段定位用户。
7. 本地测试：使用 ngrok http 3000 暴露本地服务，在 Dodo 测试面板添加 ngrok 地址并触发测试事件。

适用场景

需要接入 Dodo Payments 支付或订阅事件、并同步到自有用户数据库的 Next.js 或 FastAPI 应用。

限制与注意事项

• whsec_ 前缀必须剥离：直接用原始字符串验证会静默失败，不会报错。
• 必须使用原始 body：一旦被解析并重新序列化，字节变化会导致验证失败。
• 始终返回 200：即使处理出错也应返回 200，否则 Dodo 会反复重试；错误应记录日志后排查。
• 幂等不可省略：支付提供商会重试并偶发重复投递，每个事件必须只处理一次。
• userId 必须存在：checkout 创建时若未设置 metadata.userId，Webhook 无法定位用户。
• 该技能的费用、定价、平台支持范围等信息暂未提供。