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.

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.

It might seem a little cumbersome that we don’t 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
  • A chargeback is received on the payment.

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. Please 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’ll 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, we will stop trying.

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.