Docs
  • What We Do
  • Supported Countries, Payment Methods, and Cryptocurrencies
  • Getting Started
  • Integration Guides
    • API
      • Required Headers
      • Create a User
      • Assign a Deposit Address
      • KYC
      • Link and Verify a Bank Account
        • Re-link Bank Account
        • Update Bank Account
        • Delete Bank Account
      • Transaction Limits
      • Buy Crypto (ACH)
      • Transaction Monitoring
      • Transaction History
    • React Native
      • Installation
      • Session Token and Wallet Signing
      • Preset Order Details
      • Example
      • Reference
      • Release History
      • User experience
        • Sign up
        • Sign in
        • Buy crypto
        • Settings & activity
    • React JS (Beta)
      • Installation
      • Session Token and Wallet Signing
      • Preset Orders
      • Callbacks
      • Theming
      • Example
      • Reference
      • Release History
  • API Reference
    • Endpoints
      • Auth
        • Crypto Wallet
        • Email OTP
        • SMS OTP
      • Activity
      • Bank
      • Client
      • Config
      • Crypto
      • Users
      • Wallets
      • Webhook Registrations
    • Custom Headers
    • Error Codes
    • Types Glossary
    • Postman
    • Open API Specification
    • Webhooks
  • Design Reference
    • UI/UX Starter kit
    • UI Requirements
  • Guides
    • Sandbox Testing
    • User Authentication
    • Link a new Signing Wallet to an Existing User
    • Plaid Bank Linking
      • Plaid OAuth Support
    • Client Dashboard (Alpha)
  • User Support Reference
    • User Account Flags
      • KYC Review
      • Transaction Processing
      • NSFs and Returned Payments
      • Fraud
    • Transactional Emails
Powered by GitBook
On this page

Was this helpful?

  1. API Reference

Webhooks

PreviousTypes GlossaryNextUI Requirements

Last updated 1 year ago

Was this helpful?

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

{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "events": [
    "ACTIVITY_UPDATED",
    "BANK_UPDATED",
    "KYC_UPDATED"
  ]
}
{
  "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.

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

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

Webhook APIs
found here
ActivityItem
BankAccount
KycResult