Decrypt webhook

These are the requirements and steps for decrypting a webhook. Every webhook Rio sends has the same two fields. data is the encrypted payload as a hex string, and iv is the initialization vector used to encrypt it, also as a hex string.

Structure of the message that our webhooks send

{
  "data": "bea4343c5d815cba55c6e1bcb835bcbea43432abc014f7b48a63....",
  "iv": "1aa8ebae81e116621251993df3b155d4"
}

Secret is used to decrypt the webhook payload.

Standard decryption for aes-256-cbc using the data, the iv, and the secret returned during the webhook registration.

Load the secret from the webhook registration

The secret you saved when you registered the webhook is base64 encoded, so decode it into a buffer before using it as the key. If you no longer have it, it cannot be recovered and you need to register the webhook again.

Go to register a webhook

Converts the hexadecimal IV to a byte buffer

[Recommendation] Check if the key length is 32 bytes, which is the required size for the AES-256 encryption algorithm.

TypeScript Example

const key = Buffer.from(WEBHOOK_SHARED_SECRET_ENCRYPTION_KEY, "base64");
if (key.length !== 32) {
  throw new Error("Encryption key must be 256 bits (32 bytes)");
}

Converts the hexadecimal IV to a byte buffer. Use the iv exactly as it came in the request body, since a new one is generated for every message and the payload cannot be decrypted without the matching one.

TypeScript Example

const ivBuffer = Buffer.from(iv, "hex");

Decryption

Creates a decryptor object using the AES-256 algorithm in CBC (Cipher Block Chaining) mode, the key and the IV.

TypeScript Example

const decipher = crypto.createDecipheriv("aes-256-cbc", key, ivBuffer);

Start decrypting the data and store the result.

TypeScript Example

let decrypted = decipher.update(data, "hex", "utf8");
decrypted += decipher.final("utf8");

Read the event

The decrypted result is a JSON string, so parse it to get the event. For an orders webhook this is the order, which means you can read its status field to react to where the order is in its lifecycle without polling.

TypeScript Example

const event = JSON.parse(decrypted);

Disclaimer: All technical documentation is subject to the terms and conditions, which apply supplementarily and take precedence over the documentation.

Get Started

Workflows

Decrypt webhook

Go to register a webhook