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.

1
2
3
4
5
6
7
8
9
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
  • 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 or part of the order is canceled.
  • The order or part of the order is 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.

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:

Attempt Interval Time after status change (HH:mm)
1st Immediately after status change 00:00
2nd 1 minute 00:01
3rd 2 minutes 00:03
4th 4 minutes 00:07
5th 8 minutes 00:15
6th 16 minutes 00:31
7th 29 minutes 01:00
8th 1 hour 02:00
9th 2 hours 04:00
10th 22 hours 26:00

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?

Read our support article for more information on the IP addresses that Mollie uses.

The webhook location is invalid

In this support article we explain when we return the error The webhook location is invalid and how you can solve this.

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.