Laravel Cashier Stripe Webhook完整教程：实时处理支付事件

Laravel Cashier Stripe Webhook完整教程：实时处理支付事件

【免费下载链接】cashier-stripeLaravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.项目地址: https://gitcode.com/gh_mirrors/ca/cashier-stripe

Laravel Cashier Stripe 是一个强大的工具，为开发者提供了与 Stripe 订阅计费服务交互的直观、流畅接口。本教程将详细介绍如何在 Laravel Cashier 中设置和使用 Stripe Webhook，以实时处理支付事件，确保你的应用能够及时响应订阅变更、支付成功、退款等关键业务场景。

为什么需要 Stripe Webhook？

在基于订阅的业务模型中，实时处理支付事件至关重要。Stripe Webhook 允许 Stripe 在特定事件发生时主动向你的应用发送通知，例如：

• 订阅创建或更新
• 支付成功或失败
• 发票生成或付款逾期
• 客户信息变更

通过 Webhook，你的应用可以立即响应这些事件，无需定期轮询 Stripe API，从而提高效率并确保数据一致性。

第一步：配置 Webhook 密钥

要开始使用 Stripe Webhook，首先需要在配置文件中设置 Webhook 密钥。打开config/cashier.php文件，找到webhook配置部分：

'webhook' => [ 'secret' => env('STRIPE_WEBHOOK_SECRET'), 'tolerance' => env('STRIPE_WEBHOOK_TOLERANCE', 300), ],

在.env文件中添加你的 Stripe Webhook 密钥：

STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here

这个密钥可以在 Stripe 仪表板的 Webhook 设置中找到。

第二步：设置 Webhook 路由

Laravel Cashier 已经为你预设了 Webhook 路由。查看routes/web.php文件，你会看到类似以下的代码：

Route::post('webhook', 'WebhookController@handleWebhook')->name('webhook');

默认情况下，Webhook 端点的 URL 是/stripe/webhook，但你可以通过配置CASHIER_PATH环境变量来自定义路径。

第三步：排除 CSRF 验证

由于 Stripe Webhook 请求来自外部服务，需要将 Webhook 路由排除在 CSRF 验证之外。打开app/Http/Middleware/VerifyCsrfToken.php文件，将 Webhook 路径添加到$except数组：

protected $except = [ 'stripe/*', ];

第四步：创建 Stripe Webhook 端点

Laravel Cashier 提供了一个便捷的 Artisan 命令来创建 Stripe Webhook 端点。在终端中运行：

php artisan cashier:webhook --url=https://your-domain.com/stripe/webhook

这个命令会在 Stripe 中创建一个新的 Webhook 端点，并配置必要的事件监听。你也可以通过 Stripe 仪表板手动创建 Webhook 端点。

第五步：处理 Webhook 事件

Laravel Cashier 的WebhookController已经处理了许多常见的 Stripe 事件。你可以在src/Http/Controllers/WebhookController.php文件中查看默认实现：

public function handleWebhook(Request $request) { if (config('cashier.webhook.secret')) { $this->middleware(VerifyWebhookSignature::class); } $payload = json_decode($request->getContent(), true); $method = 'handle'.Str::studly(str_replace('.', '_', $payload['type'])); if (method_exists($this, $method)) { return $this->{$method}($payload); } return $this->missingMethod($payload); }

要处理自定义事件，你可以创建自己的 Webhook 控制器并扩展WebhookController，或者监听 Cashier 触发的事件。

第六步：测试 Webhook 本地开发

在本地开发时，你需要将 Stripe Webhook 请求转发到你的本地服务器。使用 Stripe CLI 可以轻松实现这一点：

stripe listen --forward-to localhost/stripe/webhook

这条命令会启动一个监听服务，并将 Stripe Webhook 请求转发到你的本地 Laravel 应用。Stripe CLI 还会生成一个临时的 Webhook 密钥，你可以在测试时使用。

第七步：验证 Webhook 签名

为了确保 Webhook 请求确实来自 Stripe，Laravel Cashier 提供了VerifyWebhookSignature中间件。这个中间件会验证请求中的签名是否有效：

public function handle($request, Closure $next) { $signature = $request->header('Stripe-Signature'); try { WebhookSignature::verifyHeader( $request->getContent(), $signature, config('cashier.webhook.secret'), config('cashier.webhook.tolerance') ); } catch (Exception $e) { abort(400, 'Invalid webhook signature.'); } return $next($request); }

常见问题与解决方案

1. 签名验证失败

如果遇到 "Invalid webhook signature" 错误，可能的原因是：

• 使用了错误的 Webhook 密钥
• 系统时间与 Stripe 服务器时间不同步
• 请求内容被修改

解决方法：

• 确保使用正确的 Webhook 密钥（Stripe CLI 生成的密钥与仪表板中的密钥不同）
• 检查服务器时间是否准确
• 确保请求内容未被修改

2. Webhook 路由被 CSRF 保护阻止

如果收到 CSRF 相关错误，确保已将 Webhook 路径添加到VerifyCsrfToken中间件的$except数组中。

3. 本地开发时收不到 Webhook

确保已正确运行 Stripe CLI 转发命令，并且使用了正确的本地 URL。

总结

通过本教程，你已经了解了如何在 Laravel Cashier 中设置和使用 Stripe Webhook。Webhook 是实时处理支付事件的关键，它使你的应用能够及时响应订阅变更、支付状态更新等重要业务事件。

记住，在生产环境中，确保 Webhook 端点使用 HTTPS，并且正确配置了签名验证。定期检查 Webhook 日志，确保所有事件都被正确处理。

Laravel Cashier 提供了强大的 Webhook 处理功能，通过src/Http/Controllers/WebhookController.php和相关中间件，你可以轻松扩展和自定义事件处理逻辑，满足你的业务需求。

【免费下载链接】cashier-stripeLaravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.项目地址: https://gitcode.com/gh_mirrors/ca/cashier-stripe