Work with webhooks

Webhooks allow you to receive real-time notifications for events that are happening in relation to your application.

When a supported event occurs, a real-time notification is posted, via HTTP POST method, to the specified endpoint.

We currently support webhooks for the following topics:

Each topic that you subscribe to requires an individual API call.

1. Generate a client credentials token​

Get a token:

curl -k --cert transport.pem --key private.key \
--location --request POST 'https://oba-auth.revolut.com/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=draftpayments'

Response:

{
  "access_token":"<JWT client credentials>",
  "token_type":"Bearer",
  "expires_in": 2399
}

Request an access token for client credentials using the /token endpoint and the client_credentials grant type.

2. Create a webhook​

Create webhook:

curl --location --request POST 'https://apis.revolut.com/webhooks/subscribe' \
--header 'Authorization: Bearer <insert access_token>' \
--data-raw '
{
    "Topic": "draftpayments/transfers",
    "Version": 1,
    "Uri": "https://example.com"
}'

To create a webhook, make a call to the /webhooks/subscribe endpoint.

3. Get list of webhook URIs​

Get list of webhooks:

curl --location --request GET 'https://apis.revolut.com/webhooks' \
--header 'Authorization: Bearer <insert access_token>'

Response:

[{
  "Topic": "draftpayments/orders",
  "Version": 1,
  "Uri": "https://example.com"
}, {
  "Topic": "draftpayments/transfers",
  "Version": 1,
  "Uri": "https://example.com"
}, {
  "Topic": "draftpayments/tokens",
  "Version": 1,
  "Uri": "https://example.com"
}]

When the webhooks are created, make a call to the /webhooks endpoint and you can see them returned in the response.

4. Listen for notifications​

Draft payment order creation payload:

{
  "Topic": "draftpayments/orders",
  "Version": 1,
  "EventId": "e6784099-4925-430d-8a38-c51eab865620",
  "Data": {
    "Id": "b36b0bb7-c162-4919-8205-32f914b4fa29",
    "Status": "Awaiting",
    "IdempotencyKey": "8e3cffda-15d9-4596-8068-e95321319973",
    "AccessTokenId": "f947d250-0996-4cc1-b2ac-0b17a285240a"
  }
}

Draft payment order state change payload:

{
  "Topic": "draftpayments/orders",
  "Version": 1,
  "EventId": "e6784099-4925-430d-8a38-c51eab865620",
  "Data": {
    "Id": "b36b0bb7-c162-4919-8205-32f914b4fa29",
    "Status": "Processed",
    "AccessTokenId": "f947d250-0996-4cc1-b2ac-0b17a285240a"
  }
}

Draft payment transfer notification payload:

{
  "Topic": "draftpayments/transfers",
  "Version": 1,
  "EventId": "51350d68-e285-406e-8571-6f7b13f9e024",
  "Data": {
    "Id": "7e18d804-b154-4035-bc8e-7a038acbb104",
    "Status": "Pending",
    "AccessTokenId": "f947d250-0996-4cc1-b2ac-0b17a285240a"
  }
}

Consent revocation payload

{
  "Topic": "tokens",
  "Version": 1,
  "EventId": "f18b4784-36f3-41f8-871e-2869f8e40f78",
  "Data": {
    "Id": "53408510-9154-4f30-bd60-308d3558b063",
    "Status": "Terminated"
  }
}

JWKS endpoint:

https://apis.revolut.com/jwk

When draft payments are approved from the Revolut Business UI, you receive a notification that indicates a change to the state of draft payment order and its individual transfers.

The Status field corresponds to those detailed in Tutorials: Work with draft payments - Payment orders vs transfers.

Please see examples of two payloads to the right. The ID field indicates the relevant object that has changed state, while EventId can be used as a unique identifier for a specific event. For Draft Payment Order creation, we will also include the IdempotencyKey that was provided in the creation request. AccessTokenId identifies the access_token that the draft payment was created by.

The header in the request will contain a detached JWS containing a kid. Please use the JWKS endpoint to the right to validate this signature.

5. Delete a webhook​

Unsubscribe from a topic

curl --location --request POST 'https://apis.revolut.com/webhooks/unsubscribe' \
--header 'Authorization: Bearer <insert access_token>' \
--data-raw '
{
    "Topic": "draftpayments/transfers"
}'

If you no longer want to receive notifications on a webhook, you can unsubscribe by running a POST request to the /webhooks/unsubscribe endpoint.

Congratulations! You have successfully set up webhooks to receive relevant notifications about your application.