Stripe Live模式Webhook无法触发问题求助

核心排查步骤 #

1. 确认Stripe Live Webhook端点配置 #

• 登录Stripe Dashboard的Live模式，进入Webhooks页面，检查：
  • 端点URL是否是Vercel生产部署后的完整地址（比如https://your-vercel-domain.com/api/webhook），确保无拼写错误
  • 是否已勾选需要监听的事件类型：account.updated和checkout.session.completed（对应你代码中处理的事件）
  • Webhook状态是否为Enabled，无连接错误提示

2. 验证Vercel环境变量配置 #

• 进入Vercel项目的Settings → Environment Variables，确认：
  • 生产环境（Production）下的STRIPE_CONNECT_WEBHOOK_SECRET是Stripe Live模式的Webhook签名密钥（不要和测试模式密钥混淆，两者完全不同）
  • 环境变量名称和代码中使用的完全一致（大小写敏感）
  • 更新环境变量后已重新部署项目（Vercel不会自动应用环境变量变更，必须手动触发部署或推送Git更新）

3. 修正NextJS Route Handler配置 #

你的代码使用了App Router的Route Handler，但缺少禁用bodyParser的配置——NextJS默认会自动解析请求体，而Stripe需要原始未解析的请求体来验证签名。在你的route.ts文件中添加如下配置：

export const config = {
  api: {
    bodyParser: false,
  },
};

没有这个配置会导致签名验证失败，甚至可能让请求无法正常到达处理逻辑。

4. 检查Vercel部署的可访问性 #

• 确认Vercel生产部署没有设置IP限制、密码保护或其他访问控制（Stripe服务器需要能公开访问你的Webhook端点）
• 用curl或Postman手动发送请求到Webhook URL，测试是否能收到响应：

  curl -X POST https://your-vercel-domain.com/api/webhook -d "test"
  

  然后查看Vercel的Logs → Functions，确认是否有请求记录。如果没有，说明端点路径错误或部署存在问题。

5. 确认Stripe实例的密钥配置 #

检查@/lib/stripe中的初始化代码，确保生产环境使用的是Stripe Live模式的Secret Key：

import Stripe from 'stripe';

export const stripe = new Stripe(
  process.env.STRIPE_LIVE_SECRET_KEY || '', // 生产环境用Live密钥
  { apiVersion: '2024-04-10' } // 确保使用最新的API版本
);

如果生产环境仍在使用测试密钥，会导致Webhook无法正常交互。

6. 查看正确的日志位置 #

• Vercel生产环境的函数日志需要在项目Dashboard → Logs → Functions中查看，终端日志仅适用于本地开发
• Stripe Webhook的请求记录在Stripe Dashboard的Webhook端点详情页，点击Events标签，查看是否有发送失败的记录（如果有，会显示错误原因）

代码中的额外注意点 #

你的代码逻辑在测试模式下正常，但生产环境中需要注意：

• account.updated事件处理中，getDocs(q)返回的查询结果可能为空，需要确保connectedAccountId在生产环境的Firestore数据中正确关联
• checkout.session.completed事件中的metadata字段，要确保生产环境创建Checkout Session时正确传入userId、productId等参数，避免因缺失元数据导致逻辑中断

内容的提问来源于stack exchange，提问作者Luca Schrimpf