Manage webhooks

The Business API lets you create, update, retrieve and delete a webhook. You can also rotate its signing secret or retrieve failed events.

Create a webhook​

To start receiving notifications on supported events, create a webhook. In your request, include an HTTPS URL to which you want to receive the events and the list of event types that you want to subscribe to.
If you don't specify the event types, you are automatically subscribed to the default ones.

curl -X POST https://b2b.revolut.com/api/2.0/webhooks \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '{
    "url": "https://example.com",
    "events": ["TransactionCreated"]
}'

In the response, you get the webhook's ID, the URL to which the events are sent, the list of event types that you are subscribed to, and the signing secret.

To see example requests and responses:

Update a webhook​

If you want to start receiving event notifications to a different URL than you have previously set up, or if you want to change which events it should notify you about, you can update your existing webhook. In your request, provide:

• In the path: the webhook's ID
• In the body: the new HTTPS URL to which you want to receive the events and/or the list of event types that you want the webhook to notify you about

Only the fields that you specify are updated. You must provide at least one of the two request body parameters, otherwise you'll get an error.

curl -X POST https://b2b.revolut.com/api/2.0/webhooks/{webhook_id} \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <your access token>" \
  -d '{
    "url": "https://example.com/webhook-new",
    "events": ["TransactionCreated"]
}'

In the response, you get the webhook's ID, the URL to which the events are sent, and the list of event types that you are subscribed to.

To see example requests and responses:

Retrieve a list of webhooks​

You can list all the existing webhooks that you have previously set up.

curl -L -X GET 'https://b2b.revolut.com/api/2.0/webhooks' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

In the response, for each webhook you get its ID, URL and list of event types that you are subscribed to.

Retrieve a specific webhook​

You can retrieve an existing webhook that you have previously set up to get its details, such as:

• The URL to which event notifications are sent
• The signing secret which you can use to verify the payload signature
• The list of event types that you are subscribed to

In your request, provide the webhook's ID as a path parameter.

curl -X GET https://b2b.revolut.com/api/2.0/webhooks/{webhook_id} \
  -H "Authorization: Bearer <your access token>"

In the response, you get your webhook's details.

To see example requests and responses:

Retrieve a list of failed webhook events​

Occasionally, events might fail to be delivered. This might happen for a number of reasons, including but not limited to timeouts, redirections, or unauthorised access. In such a case, Revolut employs a retry mechanism.

If, despite the retries, the event is still not delivered, you can check it by retrieving the list of failed webhook events.

In the path, provide the ID of the webhook for which you want to get the failed events.

curl -L -g -X GET 'https://b2b.revolut.com/api/2.0/webhooks/{webhook_id}/failed-events' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

The returned events are paginated and listed by their created_at date in reverse chronological order .

To see example requests and responses:

Filtering and pagination​

You can also include the optional query parameters to:

• Modify the maximum number of events returned per page (by default, it's 100)
• Retrieve only the events which were created before a date/date-time that you specify

For example, these parameters limit the number of events to three and retrieve only the events created before 13th June 2023:

/webhooks/{webhook_id}/failed-events?limit=3&created_before=2023-06-13

To get to the next page, make a new request and use the created_at date of the last returned event as created_before.

Rotate a webhook signing secret​

If you suspect that your webhook signing secret has been compromised, you can rotate it.

If you pass the optional expiration_period parameter, the old secret remains valid until the expiration period has passed. Otherwise, it is invalidated immediately.

This means that in the period when multiple signing secrets remain valid, multiple signatures are sent.

To rotate a webhook signing secret, use the following request:

curl -X POST https://b2b.revolut.com/api/2.0/webhooks/{webhook_id}/rotate-signing-secret \
  -H "Authorization: Bearer <your access token>"

In the response, you get a new signing_secret to use.

To see example requests and responses:

Delete a webhook​

If you no longer want to receive event notifications, you can delete your webhook.

In your request, provide the ID of the webhook you wish to delete as a path parameter.

curl -L -X DELETE 'https://b2b.revolut.com/api/2.0/webhooks/{webhook_id}' \
-H 'Authorization: Bearer <TOKEN>'

On successful deletion, you don't get any content in the response.

To see example requests and responses: