Events & Webhooks

Purpose

Webhooks allow your application to receive real-time notifications when specific events occur (e.g., a client's status changes). This helps you avoid constant polling.

When to Use

Use webhooks if your application requires immediate updates upon events. Otherwise, periodic polling may suffice.

Testing Endpoints

You can test these endpoints directly in our API Sandbox.

Available Events

The following events can be subscribed to:

Event	Description
account.status.opened	Triggered when an account is opened
account.status.blocked	Triggered when an account is blocked
account.status.unblocked	Triggered when an account is unblocked
identity.blocked	Triggered when an identity is blocked
identity.unblocked	Triggered when an identity is unblocked
identity.closed	Triggered when an identity is closed
payment_transaction.external_refused	Triggered when an external payment transaction is refused
payment_transaction.settled	Triggered when a payment transaction is settled
transaction.new	Triggered when a new transaction is created
iban_structure.created	Triggered when an IBAN structure is created
iban_structure.field_updated	Triggered when an IBAN structure field is updated
iban_structure.file_imported	Triggered when an IBAN structure file is imported

Webhook Management

Subscribe to a Webhook

Subscribe to receive notifications for specific events.

Endpoint

POSThttps://sandbox.revsto.com/api/distributor/v1/hooks

Required Scopes: event_management

Code Examples

cURL

curl -X POST "https://sandbox.revsto.com/api/distributor/v1/hooks" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your_api_token" \
-d '{"name": "revsto test", "url": "https://yourdomain.com/webhook", "events": ["account.status.blocked"]}'

Python

import requests

url = "https://sandbox.revsto.com/api/distributor/v1/hooks"
payload = {"name": "revsto test", "url": "https://yourdomain.com/webhook", "events": ["account.status.blocked"]}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

JavaScript

fetch("https://sandbox.revsto.com/api/distributor/v1/hooks", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer your_api_token"
    },
    body: JSON.stringify({name: "revsto test", url: "https://yourdomain.com/webhook", events: ["account.status.blocked"]})
  })
    .then(res => res.json())
    .then(data => console.log(data))
    .catch(err => console.error(err));

Request Body

Webhook Subscription Request

{
  "name": "revsto test",
  "url": "https://yourdomain.com/webhook",
  "events": ["account.status.blocked"]
}

Sample Response

Webhook Subscription Response

{
  "id": 420,
  "name": "revsto test",
  "body": "https://webhook.site/3befaaa1-4313-494d-ac4c-f58255327701",
  "distributorId": 1016,
  "events": [
      "account.credited"
  ]
}

tip

When setting up webhooks, ensure your server responds with a 200 OK status code promptly. If Revsto doesn't receive this response, it will retry the webhook delivery several times before giving up.

Managing Subscriptions

Retrieve a list of all active webhook subscriptions.

Endpoint

GEThttps://sandbox.revsto.com/api/distributor/v1/hooks

Required Scopes: event_management

cURL

curl -X GET "https://sandbox.revsto.com/api/distributor/v1/hooks" \
-H "Authorization: Bearer your_api_token"

Python

import requests

url = "https://sandbox.revsto.com/api/distributor/v1/hooks"
headers = {"Authorization": "Bearer your_api_token"}
response = requests.get(url, headers=headers)
print(response.json())

JavaScript

fetch("https://sandbox.revsto.com/api/distributor/v1/hooks", {
    headers: {"Authorization": "Bearer your_api_token"}
  })
    .then(res => res.json())
    .then(data => console.log(data))
    .catch(err => console.error(err));

Sample Response

List Webhooks Response

[
  {
      "id": 420,
      "name": "revsto test",
      "body": "https://yourdomain.com/webhook",
      "distributorId": 1016,
      "events": [
          "account.status.blocked"
      ]
  },
  {
      "id": 421,
      "name": "another webhook",
      "body": "https://yourdomain.com/another-webhook",
      "distributorId": 1016,
      "events": [
          "transaction.new"
      ]
  }
]

Unsubscribe

Remove a webhook subscription to stop receiving event notifications.

Endpoint

DELETEhttps://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}

Required Scopes: event_management

cURL

curl -X DELETE "https://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}" \
-H "Authorization: Bearer your_api_token"

Python

import requests

hookId = "abc123"  # Replace with your actual hook ID
url = f"https://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}"
headers = {"Authorization": "Bearer your_api_token"}
response = requests.delete(url, headers=headers)
print(response.json())

JavaScript

const hookId = "abc123";  // Replace with your actual hook ID
fetch(`https://sandbox.revsto.com/api/distributor/v1/hooks/${hookId}`, {
  method: "DELETE",
  headers: {"Authorization": "Bearer your_api_token"}
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Sample Response

Delete Webhook Response

{
  "message": "Webhook subscription successfully deleted",
  "hookId": "abc123"
}

Associate Hook with Identity

Link a webhook subscription to a specific user identity to receive events related to that user.

Endpoint

POSThttps://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}/identities/{identityId}

Required Scopes: event_management

cURL

curl -X POST "https://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}/identities/{identityId}" \
-H "Authorization: Bearer your_api_token"

Python

import requests

hookId = "abc123"  # Replace with your actual hook ID
identityId = "user456"  # Replace with your actual identity ID
url = f"https://sandbox.revsto.com/api/distributor/v1/hooks/{hookId}/identities/{identityId}"
headers = {"Authorization": "Bearer your_api_token"}
response = requests.post(url, headers=headers)
print(response.json())

JavaScript

const hookId = "abc123";  // Replace with your actual hook ID
const identityId = "user456";  // Replace with your actual identity ID
fetch(`https://sandbox.revsto.com/api/distributor/v1/hooks/${hookId}/identities/${identityId}`, {
  method: "POST",
  headers: {"Authorization": "Bearer your_api_token"}
})
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

Sample Response

Associate Hook Response

{
  "message": "Hook successfully associated with identity",
  "hookId": "abc123",
  "identityId": "user456"
}

Webhook Payload Format

When an event occurs, Revsto will send a POST request to your webhook URL with a JSON payload.

Example Payload

Webhook Payload Example

{
  "id": "9728",
  "webhookId": "0196a9bd-a943-72b4-aaf3-a559121beb23",
  "type": "account",
  "event": "account.status.opened",
  "data": {
      "accountNumber": "10000097286",
      "ownerIdentityId": 3639
  }
}

Security Considerations

Webhook Signature Verification

For security, each webhook request includes a signature in the X-Revsto-Signature header. Verify this signature to ensure the webhook is from Revsto.

// Example signature verification in Node.js
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const calculatedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculatedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Rate Limiting and Retries

• Webhooks are rate-limited to 100 requests per minute per endpoint
• Failed deliveries are retried with exponential backoff:
  • 1st retry: 5 seconds
  • 2nd retry: 30 seconds
  • 3rd retry: 2 minutes
  • 4th retry: 10 minutes
  • 5th retry: 30 minutes (final attempt)

caution

If real-time updates are not critical, consider periodic polling instead of using webhooks.