跳到主要内容

Stripe 数据套餐 Webhook 配置

本项目为蜂窝数据套餐购买使用了独立的 Stripe webhook 端点：

  • https://aovis.app/api/webhooks/data-plan

请把这个端点和现有的硬件订单 webhook /api/stripe/webhook 分开维护。

Stripe 控制台步骤​

  1. 打开 Stripe Dashboard。
  2. 进入 Developers -> Webhooks。
  3. 点击 Add endpoint。
  4. 将端点 URL 设置为：
    • https://aovis.app/api/webhooks/data-plan
  5. 不要修改现有的硬件订单 webhook 端点。
    • 建议单独再建一个 webhook，只用于数据套餐，这样硬件订单流程保持隔离。

需要订阅的事件​

新端点订阅这些 Stripe 事件：

  • checkout.session.completed
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • charge.refunded

重要说明：

  • Stripe 在 Dashboard 级别不支持按 metadata.type 过滤 webhook 事件。
  • 过滤必须在应用代码中完成。
  • 当前实现已经在 app/api/webhooks/data-plan/route.ts 中检查 session.metadata.type === 'data_plan'，只有满足条件才会创建 DataPlanPurchase。
  • 无关事件会直接返回 200，这样 Stripe 不会重试。

签名密钥​

创建端点后：

  1. 打开新端点详情页。
  2. 在 Signing secret 下点击 Reveal。
  3. 复制 whsec_... 值。
  4. 把它保存到 VM 上：
    • STRIPE_DATA_PLAN_WEBHOOK_SECRET=whsec_...

这个变量必须手动追加到 VM 的 .env.production，不要提交到 git，也不要整文件覆盖。

验证清单​

完成端点创建并把密钥加到 VM 后：

  1. 在 Stripe Dashboard 发送一次测试事件到新端点。
  2. 确认 Stripe 显示投递结果为 200。
  3. 检查服务器日志，确认事件已收到：
    • pm2 logs aovis-store-staging --lines 200
  4. 跑一次真实或测试的数据套餐购买，确认会创建一条 DataPlanPurchase 记录。