本文旨在解决 Laravel 应用中 Mollie Webhook 不工作的问题。核心原因是 Laravel 默认的 CSRF 保护机制会阻止外部 POST 请求，包括 Mollie 的 webhook 调用。教程将详细指导如何通过在 `VerifyCsrfToken` 中间件的 `$except` 数组中添加 webhook URL 来豁免 CSRF 保护，并提供相关代码示例及生产环境下的安全最佳实践。
理解 Webhook 与 Laravel CSRF 保护
Webhook 是一种通过 HTTP 回调机制实现应用间实时通信的方式。在支付场景中，如 Mollie 支付网关，当交易状态发生变化（例如支付成功）时，Mollie 会向预设的 webhookUrl 发送一个 HTTP POST 请求，通知您的 Laravel 应用进行后续处理，如更新订单状态、生成发票等。
Laravel 框架为了防止跨站请求伪造（CSRF）攻击，默认对所有 POST、PUT、PATCH 和 DELETE HTTP 请求实施 CSRF 保护。这意味着，除非请求包含有效的 CSRF token，否则这些请求将被拒绝。然而，Mollie 等第三方服务发送的 webhook 请求不会携带 Laravel 生成的 CSRF token，因此会被 Laravel 的 CSRF 保护机制错误地拦截，导致 webhook 处理器无法被调用，且通常不会抛出明确的错误信息。
Mollie 支付集成中的 Webhook 设置
在 Laravel 应用中集成 Mollie 支付时，通常会在创建支付请求时指定 webhookUrl。例如：
use Mollie\Laravel\Facades\Mollie;
use Illuminate\Support\Str;
use Illuminate\Support\Facades\Auth;
public function order()
{
$user = Auth::user();
$payment = Mollie::api()->payments()->create([
'amount' => [
'currency' => 'EUR',
'value' => number_format($this->service->price, 2, '.', '')
],
'description' => 'Order #' . Str::random(6),
'redirectUrl' => route('service.order.callback'),
'webhookUrl' => route('service.order.webhook'), // 关键：指定 webhook URL
'metadata' => [
'user' => [
'id' => $user->id,
'name' => $user->name,
],
'invoice' => [
'id' => 0
]
]
]);
return $this->redirect($payment->getCheckoutUrl(), 303);
}对应的 webhook 路由定义在 web.php 中，通常是一个 POST 请求：
use App\Http\Controllers\Payment\Invoice;
Route::post('/service/order/webhook', [Invoice::class, 'webhook'])->name('service.order.webhook');而 Invoice 控制器中的 webhook 方法，负责处理 Mollie 发送的回调：
use App\Models\Payment\Invoice as InvoiceModel;
use Carbon\Carbon;
public function webhook()
{
// 此时 Mollie 的数据应通过请求体传入，这里仅为示例
// 实际应用中需要从请求中获取 Mollie Payment ID，并使用 Mollie API 验证支付状态
$invoiceUser = InvoiceModel::create([
'status' => 'paid',
'number' => '1',
'date' => Carbon::now(),
'billing_detail_id' => 1,
'payment_id' => 1 // 实际应为 Mollie 支付 ID
]);
// 重要的是，此方法需要被成功调用
}当上述 webhook 方法未被调用时，通常意味着请求在到达控制器之前就被拦截了。
解决方案：豁免 Webhook URL 的 CSRF 保护
解决 Mollie Webhook 不工作问题的关键在于，将您的 webhook URL 添加到 Laravel CSRF 保护的例外列表中。这通过修改 app/Http/Middleware/VerifyCsrfToken.php 文件来实现。
- 打开 app/Http/Middleware/VerifyCsrfToken.php 文件。
- 找到 $except 属性。 这是一个受保护的数组，用于存放不需要 CSRF 验证的 URI。
- 将您的 webhook URL 添加到 $except 数组中。 请确保使用与路由定义中完全匹配的 URI 路径。
<?php
namespace App\Http\Middleware;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken as Middleware;
class VerifyCsrfToken extends Middleware
{
/**
* The URIs that should be excluded from CSRF verification.
*
* @var array<int, string>
*/
protected $except = [
// ... 其他可能已有的例外
'/service/order/webhook', // 添加您的 Mollie Webhook URL
];
}完成此修改后，当 Mollie 向 /service/order/webhook 发送 POST 请求时，Laravel 将不再对其进行 CSRF token 验证，从而允许请求正常到达您的 Invoice 控制器中的 webhook 方法。
生产环境下的安全最佳实践
虽然豁免 CSRF 保护解决了 webhook 调用问题，但在生产环境中，还需要考虑额外的安全措施：
-
验证 Webhook 签名： Mollie 等许多支付服务会在 webhook 请求中包含一个签名或哈希值。您的应用应该使用 Mollie 提供的密钥来验证这个签名，以确保请求确实来自 Mollie，而不是恶意第三方。这可以防止伪造的 webhook 请求。
- Mollie 通常会在请求头中提供签名，您可以使用 Mollie PHP SDK 或手动计算并比对。
幂等性处理： Webhook 请求可能会因为网络问题或其他原因被重复发送。您的 webhook 处理器应该设计成幂等性的，即多次处理同一个 webhook 请求不会导致重复的副作用（例如，不会多次扣款或创建多张发票）。通常，这可以通过存储已处理的 Mollie Payment ID 并检查其是否已存在来实现。
异步处理 Webhook： Webhook 处理逻辑可能涉及数据库操作、外部 API 调用等耗时任务。为了避免 Mollie 服务器因等待响应超时而重试发送 webhook，建议将 webhook 的实际处理逻辑放入队列中异步执行。您的 webhook 处理器可以快速地接收请求、验证签名，然后将任务推送到队列中，并立即返回一个 200 OK 响应。
详细日志记录： 记录所有接收到的 webhook 请求的详细信息，包括请求头、请求体、处理结果等。这对于调试和审计至关重要。
限流与监控： 监控 webhook 端点的访问情况，并考虑实施限流策略，以防止潜在的拒绝服务攻击。
总结
在 Laravel 中集成 Mollie Webhook 时，最常见的“不工作”问题源于 Laravel 默认的 CSRF 保护机制。通过在 VerifyCsrfToken 中间件的 $except 数组中添加 webhook URL，可以有效地解决这一问题。同时，为了确保生产环境下的安全性和稳定性，务必结合验证 webhook 签名、实现幂等性、采用异步处理以及详细日志记录等最佳实践。遵循这些指导原则，将确保您的 Laravel 应用能够可靠且安全地处理来自 Mollie 的支付通知。
