Work with webhooks

A webhook (also called a web callback) allows your system to receive updates about your account to an HTTPS endpoint that you provide. When a supported event occurs, a notification is sent via HTTP POST method to the specified endpoint.

Supported event types​

The following events are supported:

• TransactionCreated
• TransactionStateChanged

Set up a webhook​

You can use the Business API to set up a webhook URL to receive a notification on every supported event:

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/webhook"
}'

Include the following request parameter:

Manage webhooks​

You can also use the Business API to manage your webhooks:

• Retrieve webhooks to check what webhooks you have configured
• Delete a webhook and stop receiving events to your specified URL
• Update a webhook URL
• Rotate a webhook signing secret

Webhook examples​

See below the examples of the different types of webhooks:

Transaction created event​

See an example of a TransactionCreated event:

{
  "event": "TransactionCreated",
  "timestamp": "2023-01-26T16:22:21.753463Z",
  "data": {
    "id": "63d2a8bd-8b67-a2de-b1d2-b58ee21d7073",
    "type": "transfer",
    "state": "pending",
    "request_id": "6a8b2ad9-d8b9-4348-9207-1c5737ccf11b",
    "created_at": "2023-01-26T16:22:21.765313Z",
    "updated_at": "2023-01-26T16:22:21.765313Z",
    "reference": "To John Doe",
    "legs": [
      {
        "leg_id": "63d2a8bd-8b67-a2de-0000-b58ee21d7073",
        "account_id": "05018b0d-e67c-4fec-bea6-415e9da9432c",
        "counterparty": {
          "id": "7e18625a-3e6c-4d4f-8429-216c25309a5f",
          "account_type": "external",
          "account_id": "ff29e658-f07f-4d81-bc0f-7ad0ff141357"
        },
        "amount": -10,
        "currency": "GBP",
        "description": "To Acme Corp"
      }
    ]
  }
}

Transaction state changed event​

See the example of a TransactionStateChanged event:

{
  "event": "TransactionStateChanged",
  "timestamp": "2023-04-06T12:21:49.865Z",
  "data": {
    "id": "9a6434d8-3581-4faa-988b-48875e785be7",
    "request_id": "6a8b2ad9-d8b9-4348-9207-1c5737ccf11b",
    "old_state": "pending",
    "new_state": "reverted"
  }
}

Retries and errors​

If the webhook URL returns an HTTP error response and the delivery of the webhook fails, Revolut will retry the webhook event for 3 more times, each with a 10-minute interval.

IP Allowlisting​

Webhook notifications are sent from the following IP addresses, in case you need to allowlist them:

• 34.77.201.175
• 34.77.253.1
• 35.197.250.116
• 35.197.227.215
• 35.246.21.235
• 34.89.70.170

Security​

Each webhook notification contains the following headers:

• Revolut-Request-Timestamp: Timestamp of the webhook event.

• Revolut-Signature: Signature of the request payload. Contains the current version of the signature generating algorithm, and the hexadecimal-encoded signature itself, for example: v1=09a9989dd8d9282c1d34974fc730f5cbfc4f4296941247e90ae5256590a11e8c.

  note

  The Revolut-Signature header can contain multiple signatures if multiple signing secrets are active at a given moment. If that's the case, they are separated by a comma. For example:

  Revolut-Signature: v1=4fce70bda66b2e713be09fbb7ab1b31b0c8976ea4eeb01b244db7b99aa6482cb,v1=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
  

Retrieve a webhook signing secret​

To ensure that a webhook request originates from Revolut and not a third party, we recommend that you verify the request's signature using a signing secret. It is generated on webhook creation, and it only changes on the secret's rotation.

Revolut uses the HMAC SHA-256 algorithm to sign its webhooks. To obtain the signing secret, make a request to the following endpoint:

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

In the response, you get signing_secret, which you can later use to verify the payload signature:

{
   "id": "12345678-1234-1234-1234-123456781234",
   "url": "https://example.com/webhook",
   "signing_secret": "wsk_P5NCcAhGWRwXuLdSNfFkPPQHAgL97BKj"
}

Verify the payload signature​

Follow these steps to verify the signature for the webhook's request payload:

1. Prepare the payload to sign​

To calculate the payload_to_sign string, concatenate the version, Revolut-Request-Timestamp, and the raw webhook payload without spaces, all separated by a full stop (.):

payload_to_sign = ${version}.${Revolut-Request-Timestamp}.${raw-payload}

An example of payload_to_sign might look like this:

v1.1683650202360.{"data":{"id":"645a7696-1234-aa47-1234-cbae0449cc46","new_state":"completed","old_state":"pending","request_id":"app_charges-9f5d5eb3-1234-1234-1234-3914763e0bcb"},"event":"TransactionStateChanged","timestamp":"2023-05-09T16:36:38.028960Z"}

2. Compute the expected signature​

Compute the hash-based message authentication code (HMAC) using the SHA256 hash function, the signing_secret for the webhook as the key and the signed_secret string as the message.

For example, you can use the following Python implementation as a reference:

import hmac
import hashlib

signing_secret = 'wsk_r59a4HfWVAKycbCaNO1RvgCJec02gRd8'

raw_payload = '{"data":{"id":"645a7696-22f3-aa47-9c74-cbae0449cc46","new_state":"completed","old_state":"pending","request_id":"app_charges-9f5d5eb3-1e06-46c5-b1c0-3914763e0bcb"},"event":"TransactionStateChanged","timestamp":"2023-05-09T16:36:38.028960Z"}'
timestamp = '1683650202360'
payload_to_sign = 'v1.' + timestamp + '.' + raw_payload

signature = 'v1=' + hmac.new(bytes(signing_secret , 'utf-8'), msg = bytes(payload_to_sign , 'utf-8'), digestmod = hashlib.sha256).hexdigest()

print(signature)

3. Compare signatures​

Once you've computed the expected signature, compare it with the signature obtained in the Revolut-Signature header of the webhook notification.

The computed signature must match exactly the signature (or one of the multiple signatures) sent in that header.

Rotate a webhook signing secret​

You can rotate a webhook signing secret using 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>"

As a response, you get a new signing_secret to use.

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.

Timestamp validation​

You can mitigate replay attacks in your webhooks by applying timestamp validation.

For each webhook event, Revolut sends a Revolut-Request-Timestamp header with the exact date-time in which it was delivered.
To validate the event, make sure that the Revolut-Request-Timestamp date-time is within a 5-minute time tolerance of the current universal time (UTC).