webhook.md

Process realtime status updates with a webhook

A webhook is a URL Mollie will call when an object’s status changes, for example when a payment changes from open to paid. More specifics can be found in the webhook guide.

To implement the webhook in your Laravel application you need to provide a webhookUrl parameter when creating a payment (or subscription):

$payment = Mollie::api()->payments->create([
    'amount' => [
        'currency' => 'EUR',
        'value' => '10.00', // You must send the correct number of decimals, thus we enforce the use of strings
    ],
    'description' => 'My first API payment',
    'redirectUrl' => 'https://webshop.example.org/order/12345/',
    'webhookUrl'   => route('webhooks.mollie'),
]);

And create a matching route and controller for the webhook in your application:

// routes/web.php

Route::name('webhooks.mollie')->post('webhooks/mollie', 'MollieWebhookController@handle');

// App/Http/Controllers/MollieWebhookController.php

class MollieWebhookController extends Controller {
    public function handle(Request $request) {
        if (! $request->has('id')) {
            return;
        }

        $payment = Mollie::api()->payments->get($request->id);

        if ($payment->isPaid()) {
            // do your thing...
        }
    }
}

Finally, it is strongly advised to disable the VerifyCsrfToken middleware, which is included in the web middleware group by default. (Out of the box, Laravel applies the web middleware group to all routes in routes/web.php.)

You can exclude the route from the CSRF protection in your bootstrap/app.php:

// bootstrap/app.php

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(
        except: ['webhooks/mollie']
    );
})

If this solution does not work, open an issue so we can assist you.