---
api: 'Merchant API'
---

# Create a webhook

Set up a webhook URL so that the Merchant API can push event notifications to the specified URL.
:::warning
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.
:::

## Endpoint

POST `/api/webhooks`

## Request body

### Attributes

- `url` (string)
    Your webhook's URL to which event notifications will be sent. 
    
    Must be a valid HTTP or HTTPS URL, capable of receiving `POST` requests.
    
    :::warning
    Restrictions:
    - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
    - URI scheme is required and must be either `http` or `https`
    - URI host is required and cannot be `localhost` or an IP address
    - Max length: `2000`
    - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
    :::
- `events` (array of enum)
    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`   | <ul> <li>`ORDER_COMPLETED`</li> <li>`ORDER_AUTHORISED`</li> <li>`ORDER_CANCELLED`</li> <li>`ORDER_FAILED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_DECLINED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_FAILED`</li> </ul> |
      | `Payment` | <ul> <li>`ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`</li> <li>`ORDER_PAYMENT_AUTHENTICATED`</li> <li>`ORDER_PAYMENT_AUTHORISATION_STARTED`</li> <li>`ORDER_PAYMENT_DECLINED`</li> <li>`ORDER_PAYMENT_FAILED`</li> </ul> |
      | `Subscription`  | <ul> <li>`SUBSCRIPTION_INITIATED`</li> <li>`SUBSCRIPTION_FINISHED`</li> <li>`SUBSCRIPTION_CANCELLED`</li> <li>`SUBSCRIPTION_OVERDUE`</li></ul> |
      | `Payout`  | <ul> <li>`PAYOUT_INITIATED`</li> <li>`PAYOUT_COMPLETED`</li> <li>`PAYOUT_FAILED`</li> </ul> |
      | `Dispute`  | <ul> <li>`DISPUTE_ACTION_REQUIRED`</li> <li>`DISPUTE_UNDER_REVIEW`</li> <li>`DISPUTE_WON`</li> <li>`DISPUTE_LOST`</li></ul> |

## Returns

### 200

OK

#### Response attributes

- `id` (string)
    The ID of the webhook.
- `url` (string)
    Your webhook's URL to which event notifications will be sent. 
    
    Must be a valid HTTP or HTTPS URL, capable of receiving `POST` requests.
    
    :::warning
    Restrictions:
    - Must be a valid URI as defined by [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
    - URI scheme is required and must be either `http` or `https`
    - URI host is required and cannot be `localhost` or an IP address
    - Max length: `2000`
    - Reserved or invalid characters must be percent-encoded (for example, use `%20` instead of a space)
    :::
- `events` (array of enum)
    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`   | <ul> <li>`ORDER_COMPLETED`</li> <li>`ORDER_AUTHORISED`</li> <li>`ORDER_CANCELLED`</li> <li>`ORDER_FAILED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_AUTHORISED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_DECLINED`</li> <li>`ORDER_INCREMENTAL_AUTHORISATION_FAILED`</li> </ul> |
      | `Payment` | <ul> <li>`ORDER_PAYMENT_AUTHENTICATION_CHALLENGED`</li> <li>`ORDER_PAYMENT_AUTHENTICATED`</li> <li>`ORDER_PAYMENT_AUTHORISATION_STARTED`</li> <li>`ORDER_PAYMENT_DECLINED`</li> <li>`ORDER_PAYMENT_FAILED`</li> </ul> |
      | `Subscription`  | <ul> <li>`SUBSCRIPTION_INITIATED`</li> <li>`SUBSCRIPTION_FINISHED`</li> <li>`SUBSCRIPTION_CANCELLED`</li> <li>`SUBSCRIPTION_OVERDUE`</li></ul> |
      | `Payout`  | <ul> <li>`PAYOUT_INITIATED`</li> <li>`PAYOUT_COMPLETED`</li> <li>`PAYOUT_FAILED`</li> </ul> |
      | `Dispute`  | <ul> <li>`DISPUTE_ACTION_REQUIRED`</li> <li>`DISPUTE_UNDER_REVIEW`</li> <li>`DISPUTE_WON`</li> <li>`DISPUTE_LOST`</li></ul> |
- `signing_secret` (string)
    The signing secret for the webhook. Use it to verify the signature for the webhook request's payload.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 422 | Unprocessable Content |

## 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](https://developer.revolut.com/docs/api/merchant#create-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](https://developer.revolut.com/docs/guides/merchant/monitor-and-observe/webhooks/using-webhooks).
:::

### 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`

#### Parameters

##### header parameters

- `Revolut-Request-Timestamp` (string, required)
  The [UNIX timestamp](https://www.unixtimestamp.com/) 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](https://developer.revolut.com/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature)
  :::

- `Revolut-Signature` (string, required)
  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](https://developer.revolut.com/docs/guides/merchant/monitor-and-observe/webhooks/verify-the-payload-signature)
  :::

#### Request body

##### Attributes

#### Returns

##### 204

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`.
:::

#### Error responses

| HTTP status code | Description |
| --- | --- |
| 4XX | If the webhook event delivery times out or the delivery of the events fails, you can respond with any HTTP `4XX` code. In this case, Revolut will retry sending the webhook event 3 more times, each with a 10-minute delay. |