Use webhooks to track order and payment lifecycle

To understand how your payments progress in their lifecycle, you can set up notifications to track changes. To do this, you can use our Webhooks endpoint.

A webhook (also called a web callback) allows your system to receive an event from a different app immediately after it happens. You can set up webhooks for different events and your system will receive a notification to a specified URL whenever each of these events happen.

info

For more information about the order and payment lifecycle, see: Order and payment lifecycle.

1. Configure a webhook to receive events​

You can use our Merchant API to set up a webhook URL and specify the events in the request body that you would like to receive.

You need a URL to receive the events. This needs to be an endpoint on your server to which our internal systems can send POST requests whenever the events happen.

caution

Merchants can register a maximum of 10 webhook URLs. If you attempt to register more than 10, the API will return a 422 - Unprocessable Content error.

Ensure your webhook registrations are necessary and within the allowed limit.

2. Receive and handle the web callback​

Once the events you have subscribed to occur, we will send a callback to the URL you have provided. It is now up to you to handle the information that your system receives.

Example structure of the events our system sends:

{
  "event": "ORDER_COMPLETED",
  "order_id": "9fc01989-3f61-4484-a5d9-ffe768531be9",
  "merchant_order_ext_ref": "Test #3928"
}

info

For more information about webhook events, see: Webhook callbacks.

warning

We cannot guarantee the delivery order of the events. You might receive the events in an unexpected order. Make sure your server does not rely on the temporal order of events.

Retry policy and errors​

If a request sent to your webhook URL returns an HTTP error response or times out and the delivery of the events fails, Revolut will retry sending the webhook event 3 more times, each with a 10-minute interval.

IP allowlisting​

For enhanced security, please ensure that your server allowlists the following IP addresses from which webhook notifications originate. Allowlisting these IPs helps ensure that your webhook endpoint only accepts requests from our trusted sources.

Production webhook IPs:

• 35.246.21.235
• 34.89.70.170

Sandbox webhook IPs:

• 35.242.130.242
• 35.242.162.241

What's next​

Now that you can use webhooks to track the payment lifecycle more effectively, there are two scenarios where we recommend using webhooks:

• Order completion: To know when a payment is successful, is to ensure the status of the order is completed. Instead of only relying on the onSuccess callback that is executed from the widget, set up a webhook URL for receiving ORDER_COMPLETED events. This is a much more robust approach to moving your own orders to a "successful" state and giving your product or service to your customers.
• Payment failure: You can set a webhook URL for receiving the ORDER_PAYMENT_FAILED and the ORDER_PAYMENT_DECLINED events. This will allow your backend to track when a payment for an order fails. You can use this together with the decline_reason parameter in the payment object. You can retrieve the decline_reason by retrieving the corresponding order for the payment.