Guides • Build Banking Apps
Work with webhooks
doc

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:

TopicDescription
draftpayments/ordersNotifications for changes of state in a draft payment order.
draftpayments/transfersNotifications for changes of state in a draft payment transfer.
tokensNotification when a user revokes consent for your application. Identify the token leveraging the access_token_id returned with access_token in previous tutorials.

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

caution

If a user revokes the consent for your application, events for objects created using this token will not be sent.

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.

note
tokens topic works for all consents no matter the scope. Depending on your application, adjust the scope parameter accordingly.

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.

note

Currently, only one webhook URI per topic is supported. Subscribing to the same topic multiple times overwrites the previous webhook URI.

3. Get list of webhook URIs

Get list of webhooks:

curl --location --request GET 'https://oba.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.

tip

We guarantee at-least-once delivery of webhooks, all duplicate events will have the same EventId.

5. Delete a webhook

Unsubscribe from a topic

curl --location --request POST 'https://oba.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.

Was this page helpful?