About 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​

You can subscribe to the following event types:

• TransactionCreated
• TransactionStateChanged
• PayoutLinkCreated
• PayoutLinkStateChanged

To subscribe to selected event types, provide their names on webhook creation or update.

Default event types​

If you don't specify which event types you want to subscribe to, you're automatically subscribed to the default event types: TransactionCreated and TransactionStateChanged.

Supported operations​

The Business API supports the following operations on webhooks:

• Create a webhook to start receiving selected events to a specified URL
• Retrieve a list of webhooks to check what webhooks you have configured
• Retrieve a specific webhook by its ID
• Delete a webhook and stop receiving events to your specified URL
• Update a webhook to change the URL or the events that you're subscribed to
• Rotate a webhook signing secret
• Retrieve a list of failed webhook events

Webhook examples​

See below the examples of different types of events that webhooks can receive.

Transaction created event​

See an example of the 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 an example of the 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"
  }
}

Payout link created event​

See an example of the PayoutLinkCreated event:

{
  "event": "PayoutLinkCreated",
  "timestamp": "2023-07-05T16:22:21.753463Z",
  "data": {
    "id": "3b9087bb-290a-4321-8ef6-96b9a2f071e8",
    "state": "created",
    "request_id": "ff5fadff-aae1-4848-87f8-53d515eea3b5"
  }
}

Payout link state changed event​

See an example of the PayoutLinkStateChanged event:

{
  "event": "PayoutLinkStateChanged",
  "timestamp": "2023-07-06T10:12:38.568Z",
  "data": {
    "id": "0e1a8d4b-1d1e-457d-9f10-3e7007a82ea8",
    "request_id": "2e2837f5-828d-473f-85e8-5614afd3f8e8",
    "old_state": "active",
    "new_state": "processed"
  }
}

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 3 more times, each with a 10-minute interval.

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

IP Allowlisting​

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

• 35.246.21.235
• 34.89.70.170

Security​

Each webhook notification contains the following headers:

• Revolut-Request-Timestamp: Timestamp of the webhook event, for example: 1683650202360.

• 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
  

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.

Revolut uses the HMAC SHA-256 algorithm to sign its webhooks. The secret is generated on webhook creation, and it only changes on the secret's rotation. After you've created a webhook, you can retrieve the signing secret when you retrieve a specific webhook's details.

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

On rotation, you can pass the optional expiration_period parameter for the old secret to remain valid until the expiration period has passed. Otherwise, it is invalidated immediately.

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).