Webhooks

Subscribe to Ratio's webhooks to get automatic updates on resources such as KYC, bank connections, and transactions. Many of the operations for which we provide webhooks occur asynchronously; our webhooks allow you to take action immediately.

Subscribing

The first thing you need to do is to create a webhook. You should call our Webhook APIs with your Client ID and Client Secret to do this. This endpoint requires a URL and a list of subscribed events; in return, it will provide you with a secret.

It is recommended to store your webhook secret securely; this unique secret will be used to verify the webhook data. This is not the same value as your Client Secret. Once it has been created, the secret cannot be retrieved again.

Request

{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "events": [
    "ACTIVITY_UPDATED",
    "BANK_UPDATED",
    "KYC_UPDATED"
  ]
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "events": [
    "ACTIVITY_UPDATED",
    "BANK_UPDATED",
    "KYC_UPDATED"
  ],
  "secret": "secretstring",
  "createdAt": "2022-10-29T12:00:00.000Z",
  "updatedAt": "2022-10-30T12:00:00.000Z"
}

Consuming

Now that you've created a webhook and stored your webhook secret, you're ready to begin receiving webhook events.

We will POST the webhook events to the URL you've provided for all Ratio users active on your Client. In the webhook, you will receive the webhook data, a timestamp header, and a signature header.

In order to securely validate that the webhook content you receive was sent by Ratio, you will need to use your webhook secret to generate the HMAC signature and compare it to the one you receive. We use a SHA512 HMAC signature from the secret we provided you, with the timestamp and webhook content in the following format: timestamp.{jsonstring}. We then hex encode it for transmit and add it to the headers.

Typescript

const timestamp = request.headers["ratio-webhook-signature-timestamp"];
const signature = request.headers["ratio-webhook-signature"];
const data = request.body;

const hmac = createHmac("sha512", "secretstring")
  .update(timestamp + "." + JSON.stringify(data))
  .digest("hex");

const valid = hmac === signature;

Schema

{
  userId: <USER_ID>,
  event: <EVENT_ENUM>,
  id: <UNIQUE_WEBHOOK_EVENT_ID>,
  data: {
    <WEBHOOK_API_DATA_TYPE>
  }
}

• The event field will be one of the event types that you subscribed to, found here.

• The data field will be the API object that corresponds to the specific event type. This will be one of ActivityItem, BankAccount, or KycResult.