Create a webhook

Set up a webhook URL so that the Merchant API can push event notifications to the specified URL.

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.

Request​

Header Parameters

Header Parameters

Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"

This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.

It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.

info

For more information, see: Authentication

Request body

Body object

Possible length: <= 2000 characters

Your webhook's URL to which event notifications will be sent.

Must be a valid HTTP or HTTPS URL, capable of receiving POST requests.

caution

Restrictions:

• Max length of url string: 2000
• Only valid http:// or https:// domains are accepted
• Domain cannot be localhost or IP address

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED, PAYOUT_INITIATED, PAYOUT_COMPLETED, PAYOUT_FAILED, DISPUTE_ACTION_REQUIRED, DISPUTE_UNDER_REVIEW, DISPUTE_WON, DISPUTE_LOST]
Possible number of items: non-empty

List of event types that the webhook is configured to listen to.

Each event is related to status changes of a specific object in the Merchant API:

Object	Event types
Order	ORDER_COMPLETED ORDER_AUTHORISED ORDER_CANCELLED
Payment	ORDER_PAYMENT_AUTHENTICATED ORDER_PAYMENT_DECLINED ORDER_PAYMENT_FAILED
Payout	PAYOUT_INITIATED PAYOUT_COMPLETED PAYOUT_FAILED
Dispute	DISPUTE_ACTION_REQUIRED DISPUTE_UNDER_REVIEW DISPUTE_WON DISPUTE_LOST

Response​

OK

Response body

Body object

The ID of the webhook.

Possible length: <= 2000 characters

Your webhook's URL to which event notifications will be sent.

Must be a valid HTTP or HTTPS URL, capable of receiving POST requests.

caution

Restrictions:

• Max length of url string: 2000
• Only valid http:// or https:// domains are accepted
• Domain cannot be localhost or IP address

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED, PAYOUT_INITIATED, PAYOUT_COMPLETED, PAYOUT_FAILED, DISPUTE_ACTION_REQUIRED, DISPUTE_UNDER_REVIEW, DISPUTE_WON, DISPUTE_LOST]
Possible number of items: non-empty

List of event types that the webhook is configured to listen to.

Each event is related to status changes of a specific object in the Merchant API:

Object	Event types
Order	ORDER_COMPLETED ORDER_AUTHORISED ORDER_CANCELLED
Payment	ORDER_PAYMENT_AUTHENTICATED ORDER_PAYMENT_DECLINED ORDER_PAYMENT_FAILED
Payout	PAYOUT_INITIATED PAYOUT_COMPLETED PAYOUT_FAILED
Dispute	DISPUTE_ACTION_REQUIRED DISPUTE_UNDER_REVIEW DISPUTE_WON DISPUTE_LOST

The signing secret for the webhook. Use it to verify the signature for the webhook request's payload.

Callbacks​

Send webhook event to webhook URL

POST

{$request.body#/url}

The following webhook event payload is sent as a HTTP POST request to the URL registered as the merchant's webhook server via the Create a webhook operation.

The delivery of the webhook events happen asynchronously, based on the events you subscribed to.

info

For more information, see: Use webhooks to track order and payment lifecycle.

IP allowlisting

To ensure secure delivery of webhook events, please allowlist the following IP addresses from which the events originate:

Production webhook IPs:

• 35.246.21.235
• 34.89.70.170

Sandbox webhook IPs:

• 35.242.130.242
• 35.242.162.241

Callback request​

Header Parameters

Header Parameters

The UNIX timestamp of the date and time when the webhook event was sent from Revolut. Used to verify the webhook event payload was actually sent by Revolut.

info

For more information, see: Verify payload signature

The payload signature computed by Revolut using a Hash-based Message Authentication Code (HMAC). Used to verify the webhook event payload was actually sent by Revolut.

info

For more information, see: Verify payload signature

Request body

Body any

Possible values: [ORDER_COMPLETED, ORDER_AUTHORISED, ORDER_CANCELLED, ORDER_PAYMENT_AUTHENTICATED, ORDER_PAYMENT_DECLINED, ORDER_PAYMENT_FAILED, PAYOUT_INITIATED, PAYOUT_COMPLETED, PAYOUT_FAILED, DISPUTE_ACTION_REQUIRED, DISPUTE_UNDER_REVIEW, DISPUTE_WON, DISPUTE_LOST]

The event type of the webhook notification that's sent by Revolut to your webhook URL.

Each event is related to status changes of a specific object in the Merchant API:

Object	Event types
Order	ORDER_COMPLETED ORDER_AUTHORISED ORDER_CANCELLED
Payment	ORDER_PAYMENT_AUTHENTICATED ORDER_PAYMENT_DECLINED ORDER_PAYMENT_FAILED
Payout	PAYOUT_INITIATED PAYOUT_COMPLETED PAYOUT_FAILED
Dispute	DISPUTE_ACTION_REQUIRED DISPUTE_UNDER_REVIEW DISPUTE_WON DISPUTE_LOST

The ID of the order the event is related to.

The information sent during order creation in the merchant_order_data.reference field.

Callback responses​

If the webhook event was delivered successfully, we recommend to respond with a 204 code.

info

You can respond to and acknowledge the delivery of a webhook event by any HTTP response code between 200-399.