Webhooks

Process realtime status updates

A webhook is a URL Mollie will call when an object’s status changes, for example when a payment changes from open to paid. You should put a script behind this URL that – when it’s called – fetches the payment status and processes it if its status has changed.

In the example case of a payment changing to paid, you should mark the order belonging to the payment as paid accordingly.

The webhook will be called with a single POST-parameter called id, which for example will contain the value tr_d0b0E3EA3v. You should use that ID to actively fetch the payment to find out about it’s status. This step seems a little cumbersome, 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.

If an endpoint supports webhooks, you can specify the webhook URL you want to receive status changes on by providing the parameter webhookUrl.

The following endpoints support webhooks:

Webhooks for v2 API endpoints

The webhook will be called when the payment changes status to:

  • 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.

Webhooks for v1 API endpoints

The webhook will be called when the payment changes status to:

  • paid
  • expired
  • failed
  • cancelled
  • refunded
  • charged_back

What IPs will the webhook requests be originating from?

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

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 don’t get a 200 OK response, we will stop trying.

Example

The most important task your webhook script has to complete is to process orders whenever the status of a payment turns out to be paid. Therefore, please note the exact working of this process really depends on your product, your business and your website. So we’re not able to show a general example here.

To get started with webhooks, please refer to the documentation of the Mollie API client you are using.