Webhooks

Webhooks events

Rialto webhooks will allow you to be notified when a new action happened on the Rialto platform.

A webhook request will always be a POSTrequest on your specified endpoint. The body of the message will contain the webhook event encoded as a JSON and following the same structure.

{
    // Type of event
    type: "TRANSACTION_CREATED",
    // Timestamp of the event, formatted as ISO 8601 date-time
    timestamp: "2024-12-01T09:07:54.940Z",
    // Data payload, see couples (event type, event payload) below
    payload: {
        clientId: "e7c1d1db-b8ca-4586-af30-8fcc213b5353",
        transactionId: "ef497614-ba4d-422d-b226-7662b17566b7"
    }
}

Event definitions

Rialto webhooks cover several types of events. Below is a list of event types and their associated payload structure:

• Transactions events

  The payload is defined as

  {
      // ID of the client account to which the transaction belongs
      clientId: string;
      // ID of the transaction
      transactionId: string;
  }

  The following types are available:

  • TRANSACTION_CREATED: triggered when a new transaction is created,

  • TRANSACTION_INITIATED: triggered when a transaction has been initiated i.e. when Rialto has received the funds for the transaction. Rialto is now processing the transaction,

  • TRANSACTION_COMPLETED: triggered when the funds have been received by the user, completing the transaction,

  • TRANSACTION_CANCELLED: triggered when the user has cancelled a transaction,

  • TRANSACTION_DISMISSED: triggered when Rialto has dismissed a transaction of a client account.

• Bank account management events

  The payload is defined as

  {
      // ID of the client account owner of the bank account
      clientId: string;
      // ID of the bank account
      bankAccountId: string;
  }

  The following types are available:

  • BANK_ACCOUNT_REQUESTED: triggered when the user has requested a new bank account,

  • BANK_ACCOUNT_REJECTED: triggered when the Rialto team has rejected a pending bank account request,

  • BANK_ACCOUNT_APPROVED: triggered when the Rialto team has approved a pending bank account request,

  • BANK_ACCOUNT_DELETED: triggered when the user or the Rialto team has deleted an approved bank account.

• Blockchain wallet management events

  The payload is defined as

  {
      // ID of the client account owner of the bank account
      clientId: string;
      // ID of the blockchain wallet
      blockchainWalletId: string;
  }

  The following types are available:

  • BLOCKCHAIN_WALLET_REQUESTED: triggered when the user has requested a new blockchain wallet,

  • BLOCKCHAIN_WALLET_REJECTED: triggered when the Rialto team has rejected a pending blockchain wallet request,

  • BLOCKCHAIN_WALLET_APPROVED: triggered when the Rialto team has approved a pending blockchain wallet request,

  • BLOCKCHAIN_WALLET_DELETED: triggered when the user or the Rialto team has deleted an approved blockchain wallet.

• Onboarding and account events - only for Client Account Managers

  The payload is defined as

  { clientId: string }

  The following types are available:

  • ONBOARDING_UNDER_REVIEW: the client account onboarding has been filled and the Rialto team is reviewing the submitted informations,

  • ONBOARDING_RESUBMISSION_REQUIRED: The Rialto team has decided that additional information or modifications are required to the client account onboarding,

  • ONBOARDING_APPROVED: The onboarding informations are approved, the client account will need to sign the terms and conditions as a last step before being able to start transactions,

  • CLIENT_VERIFIED: The terms and conditions document has been signed by the client account. The client account is now ready for transactions,

  • TERMS_AND_CONDITIONS_VOIDED: The client account has not yet signed the terms and conditions document and there was an issue with the existing document, the later is voided and the signature process is restarted,

  • CLIENT_DELETED: The client account has been deleted by the Client Account Manager or the Rialto team.

Expected response and retries

A webhook request will be considered successful if the response has a success status code (200-299).

In case of error, webhook requests will be retried three times and following an exponential backoff strategy.

Webhooks management

A webhook can be created from your target URL and starts as active. A webhook secret will be shared at creation time in order to enable you to properly verify the messages.

Once a webhook is no longer needed, it can be deleted.

Management of the webhooks can be made:

• either via the API using the /webhooks routes,

• either via the application, in your API Settings page and its dedicated Webhooks section.

Please note the following:

• Webhook secrets are only shown once at creation time.

• Webhook secrets allow to any user that has access to them to create webhook messages with an exact signature. Webhook secrets should never be shared to an unintended audience. Please keep your webhook secret secure. If a secret is lost or publicly revealed, it is recommended to delete the webhook and re-create it.

• You can have 3 active webhooks at the same time. If you reached the limit, you need to delete one webhook before creating a new one.

Security

It is strongly recommended to protect your webhook endpoints against unwanted requests.

Each request can be verified using the webhook secret, the message content and the signature header.

If additional security is needed, the list of IPs addresses of the request sender are available for restrictions.

Verifying the signature

To each webhook is associated a secret, only visible at the webhook creation.

Using this secret, a HMAC (SHA-256) of the request body is computed, it is then base64 encoded, the value sha256=<base64 encoded HMAC>is finally added to the Rialto-Signatureheader of the webhook request.

Here is a NodeJS snippet in order to illustrate the verification of a message.

import crypto from "crypto";

const WEBHOOK_SECRET = "<Fill your secret>";

async function requestHandler(request: Request): Promise<unknown> {
  const body = await request.text();
  const signatureHeader = request.headers.get("Rialto-Signature");

  if (!signatureHeader) {
    return new Response("Unauthorized", { status: 401 });
  }

  const hmac = crypto.createHmac("sha256", WEBHOOK_SECRET);
  hmac.update(body);
  const signature = hmac.digest("base64");

  if (signatureHeader !== `sha256=${signature}`) {
    return new Response("Unauthorized", { status: 401 });
  }

  return new Response("OK", { status: 200 });
}

IPs restrictions

Webhook requests are sent from a fixed list of IPs. Additional security can be brought by restricting your endpoints to be requested from these IPs.

[
    "3.125.136.186/32",
    "18.198.95.233/32",
    "3.69.157.89/32",
    "3.69.220.58/32",
    "52.58.170.183/32",
    "3.74.98.166/32"
]