Webhooks

Webhooks are used to process real-time status updates, for example when a payment is paid. It is a URL Mollie will call with the ID of the updated object. When Mollie calls your webhook, you should fetch the latest status and process it if the status was changed.

📘

Note

Check against your records that the resource actually has been changed when your webhook is called.

Example

The most important example of a webhook is when a payment is paid. If you created the payment with a webhook URL, we will call that webhook URL with a single POST-parameter called id and a value of for example tr_d0b0E3EA3v. The script behind your webhook URL should use that ID to fetch the payment status and act accordingly. If the new payment status is paid you can start shipping the order.

POST /payments/webhook HTTP/1.0
Host: webshop.example.org
Via: 1.1 tinyproxy (tinyproxy/1.8.3)
Content-Type: application/x-www-form-urlencoded
Accept: */*
Accept-Encoding: deflate, gzip
Content-Length: 16

id=tr_d0b0E3EA3v

It might seem a little cumbersome that we do not post the new status immediately, but proper security dictates this flow. Since the status is not transmitted in the webhook, fake calls to your webhook will never result in orders being processed without being actually paid.

More examples are available in the documentation of the Mollie API client you are using.

Endpoints supporting webhooks

If an endpoint supports webhooks, you can specify the webhook URL you want to receive status changes on by providing the parameter webhookUrl. Below is a list of all endpoints that support webhooks.

Payments API

The Payments API calls a webhook when a payment reaches one of the following statuses:

• paid
• authorized
• expired
• failed
• canceled

Furthermore, the webhook will be called when:

• A refund is performed on the payment, and the refund reaches state processing, refunded or failed.
• A chargeback is received on the payment.

The webhook is not called if you have specified a method and the consumer cancels the payment on the payment page. We will redirect the customer instead towards the hosted checkout page and allow him to pick a new method. Only on cancelling on this page, the payment will receive the state canceled and the webhook will be called.

Read more about payment status changes.

Orders API

The Orders API calls a webhook when an order reaches the status paid or authorized. These statuses indicate that the order is ready to be shipped.

Furthermore, the webhook will be called when:

• A shipment is created for the order.
• The order is canceled, or order lines are canceled.
• The order is refunded, or order lines are refunded.

Read more about order status changes.

Subscriptions API

The webhook URL specified when creating a subscription is used for each payment that is created by this subscription. Refer to the explanation above for more information about webhooks for payments.

The Recurring Payments guide has some additional information about webhooks for subscriptions.

Payment Links API

The webhook URL specified when creating a payment link is called every time the underlying payment’s status changes. See the Payments API section for more on the conditions payment webhooks are called on.

Retry schema

In response to Mollie calling your webhook, you only have to return the HTTP status 200 OK. Mollie then knows your system correctly processed the request. In case you return a different status – let’s say because there’s a temporary problem with your hosting service – we will keep trying for a few hours, allowing you to process the request later on after your hosting service has been restored.

Our webhook calls time out after 15 seconds. Even if you return a 200 OK HTTP status after 16 seconds, we will mark the webhook call as failed and try again later.

In total we will call your webhook 10 times with an increasing interval. If after the 10th call we still do not get a 200 OK response (which is after 26 hours), we will stop trying.

We use the following intervals between attempts while trying to call your webhook:

How to handle unknown IDs?

To not leak any information to malicious third parties, it is recommended to return a 200 OK response even if the ID is not known to your system.

What IPs will the webhook requests be originating from?

A common way to ensure the authenticity of webhooks, is by validating whether the IP address that sent the request is a known IP address.

For the Mollie API, we recommend against this practice. As our systems continue to evolve, the IP addresses used by our webhook systems will likely change over time. If you have a fixed list of allowed IP addresses on your end, this means that sooner or later you will start missing out on our webhooks.

Instead, the Mollie API will always only send you an ID of the entity that got updated. You will need to retrieve the full entity to understand what changed, and by doing so you are ensuring your information comes directly from an authenticated Mollie API call.

The webhook location is invalid

Your webhook URL needs to be accessible from Mollie's point of view. This means that URL's like localhost will not be accepted. If you want to test webhooks locally, you should use a service like ngrok to make your local environment accessible from the internet.

Redirecting webhook calls

When our call to the webhook URL gets redirected with a 301 Moved Permanently or 302 Found response the request changes from POST to get. This causes the POST payload to drop of the webhook call. The solution is to redirect using a 307 Temporary Redirect or 308 Permanent Redirect response.

Can I manually retrigger a webhook call from Mollie?

No, it's not possible to retrigger a webhook call by yourself. We will automatically retry webhook calls which fail in case of an error on your endpoint. In case you need a successful webhook to be sent again, reach out to our support team for assistance.