Stripe Webhook与WordPress集成失败：100%错误率无事件通知

以下是针对你的WordPress自定义REST端点+Stripe Webhook场景的核心排查方向：

1. 端点URL无法被Stripe正常访问 #

• 站点的防火墙、安全插件（如Wordfence、Cloudflare）可能拦截了Stripe的请求，直接返回4xx/5xx状态码。可以暂时关闭安全插件测试，或在防火墙规则中添加Stripe的IP白名单。
• 用curl命令手动测试端点响应：

  curl -X POST https://womanverse.ro/stripewebhooks/v1/task -H "Content-Type: application/json" -d '{"type": "test.event"}'
  

  如果返回非200状态码，先解决站点的可访问性问题。

2. 自定义REST端点代码存在缺陷 #

• 未验证Stripe签名：Stripe会发送Stripe-Signature请求头，若代码未做签名验证，要么请求被你的逻辑拒绝，要么Stripe后续判定请求无效。必须在回调函数中加入签名验证逻辑：

  function your_stripe_webhook_handler( $request ) {
    $stripe_secret = '你的Webhook签名密钥';
    $signature = $request->get_header( 'Stripe-Signature' );
    $payload = $request->get_body();
  
    try {
      \Stripe\Webhook::constructEvent( $payload, $signature, $stripe_secret );
    } catch( \Exception $e ) {
      return new WP_REST_Response( null, 403 );
    }
  
    // 处理事件逻辑
    return new WP_REST_Response( null, 200 );
  }
  

• 未及时返回200响应：Stripe要求端点在10秒内返回200 OK，如果你的代码执行耗时过长（比如调用数据库、第三方API），会被Stripe标记为错误。建议先返回200，再异步处理事件逻辑。
• 代码语法/逻辑错误：开启WordPress调试模式查看错误日志：

  // 在wp-config.php中添加
  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);
  

  查看wp-content/debug.log中的PHP错误，排查代码问题。

3. Stripe后台配置错误 #

• 签名密钥不匹配：确认Stripe后台复制的Webhook签名密钥，和代码中使用的完全一致，密钥错误会直接导致验证失败。
• 事件订阅不匹配：检查你勾选的三个事件是否和实际付款场景匹配——比如即时付款不会触发checkout.session.async_payment_succeeded，但checkout.session.completed和charge.succeeded应该触发。如果实际触发的事件不在订阅列表里，自然收不到通知。
• 环境模式混淆：测试环境的Webhook只能接收测试支付事件，Live环境只能接收真实支付事件，不要搞混环境配置。

4. WordPress REST API路由或权限问题 #

• 路由冲突：自定义路由stripewebhooks/v1/task可能和其他插件/主题的路由冲突，尝试修改路由路径（比如改成/stripe-webhook/v1/handle）测试。
• 权限拦截：WordPress REST API默认要求授权，若你的端点未开放权限，Stripe的请求会被返回401。确保注册路由时设置了正确的权限回调：

  register_rest_route( 'stripewebhooks/v1', '/task', array(
    'methods' => 'POST',
    'callback' => 'your_stripe_webhook_handler',
    'permission_callback' => '__return_true', // 允许未授权POST请求
  ) );
  

5. SSL证书问题 #

Stripe要求Webhook端点必须使用有效HTTPS证书，如果你的站点证书过期、自签名或不被信任，请求会被Stripe拒绝。可以用SSL检测工具确认证书状态。

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