如何在Node.js环境中配置Stripe转账成功/失败状态的webhook监听

1 先确认操作类型对应的事件是否正确 #

这是最高频的踩坑点：

• 如果你是从自己的Stripe账户余额提现到自身绑定的银行账户，这类操作对应的Stripe对象是payout，需监听payout.paid、payout.failed事件，而非transfer相关事件
• 如果你是向Stripe关联账户（Connect平台的子账户）发起转账，才属于transfer对象，对应监听transfer.paid、transfer.failed事件

2 检查Webhook端点的事件订阅配置 #

登录Stripe Dashboard，进入对应Webhook端点的设置页，确认你已经手动勾选了transfer.paid和transfer.failed两个事件（仅在代码里写处理逻辑不会自动注册事件，必须在后台配置订阅），你之前能收到transfer.created是因为你已经勾选了该事件。

3 排查转账状态与触发时机 #

Stripe普通转账不是即时到账，标准到账周期为1-3个工作日，在转账状态变为paid前不会触发对应事件：

• 你可以在Stripe Dashboard的转账列表里查看对应转账的当前状态，如果仍为pending，属于正常情况，到账后会自动触发事件
• 测试时建议使用Stripe测试环境，用指定的测试银行账号可以触发即时到账/转账失败，快速验证逻辑

4 确认事件监听的账户归属一致 #

• 如果你用平台账户的API密钥发起的转账，事件只会发送到平台账户的Webhook端点，不会发送到关联子账户的Webhook
• 如果你用子账户的API密钥发起的转账，事件只会发送到对应子账户的Webhook端点，需确认你配置Webhook的账户和发起转账的账户一致

5 代码逻辑校验 #

不要直接解析请求体判断事件类型，必须用Stripe官方的签名校验逻辑解析事件，避免解析错误导致的判断失效，Node.js环境正确示例如下：

const stripe = require('stripe')('你的Stripe密钥');
const webhookSecret = '你的Webhook端点密钥';

// 注意这里要用express.raw保留原始请求体，不能用express.json()解析
app.post('/stripe-webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    // 官方签名校验，同时解析事件
    event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
  } catch (err) {
    return res.status(400).send(`Webhook校验失败: ${err.message}`);
  }

  switch (event.type) {
    case 'transfer.created':
      // 现有转账创建逻辑
      break;
    case 'transfer.paid':
      // 更新数据库为转账成功逻辑
      break;
    case 'transfer.failed':
      // 更新数据库为转账失败逻辑
      break;
  }

  res.status(200).json({received: true});
});

6 本地快速测试方法 #

你可以使用Stripe CLI直接向本地Webhook端点推送测试事件，无需真实发起转账即可验证逻辑：
执行命令 stripe trigger transfer.paid 即可模拟推送转账成功事件，看是否能触发对应代码块。

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