新上8卡RTX 5090 限时特惠 Read more

支付网关 Stripe Webhook 回调失败:Nginx 超时、IP 白名单与签名校验排查 - 云数方舟

支付网关 Stripe Webhook 回调失败:Nginx 超时、IP 白名单与签名校验排查

用户付了钱,Stripe 后台显示 succeeded,但你的系统里订单还是 pending。查日志发现 Webhook 回调 502 或超时——钱到了但订单没更新,最怕用户来问”我付了怎么没到账”。

断点一:Nginx 超时

Stripe Webhook 默认等 5 秒响应,你的回调接口查数据库+更新订单+发邮件总共花了 8 秒,Stripe 直接标记失败并重试。三次重试后进入 dead letter。

# Nginx 回调路径单独配超时
location /webhook/stripe {
    proxy_read_timeout 10s;
    proxy_connect_timeout 5s;
    proxy_pass http://127.0.0.1:3000;
}

代码层改成”先返回 200 再异步处理”:收到回调立即 ack,丢进队列慢慢更新订单状态。

断点二:IP 白名单拦了

防火墙或 Nginx 只放行了业务 IP,没加 Stripe 的 Webhook 出口段。Stripe 官方文档有 IP 列表,定期更新,硬编码进防火墙规则。

# 查 Stripe 当前 IP 段
curl https://stripe.com/files/ips/ips_webhooks.txt

断点三:签名校验失败

  • endpoint secret 复制错了:从 Stripe Dashboard 重新复制,别手打
  • 请求体被 Nginx 改了:开了 gzip 或 proxy_set_header 改了 Content-Type,签名对不上
  • 代码里读了 raw body 但框架自动 parse 了 JSON:Express 里要 express.raw({type:'application/json'}) 中间件先拦截

幂等必须做

Stripe 重试机制意味着你的 Webhook 可能收到同一事件两次。用 event.id 做去重表,处理前先查是否已执行过,别让用户因为重试被重复发货。

海外节点支付业务部署:云数方舟美国/香港服务器

云数方舟
  • contact@globaldc.cn