> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rio.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Decrypt webhook

<Warning>
  **v1 (legacy).** This page documents the API before the v2 update. The v1
  format is not enabled for new accounts and must be enabled on your account by
  your account manager. New integrations should use the
  [current documentation](/introduction). To update an existing integration,
  follow the [migration guide](/migration).
</Warning>

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.

```json Structure of the message that our webhooks send theme={null}
{
  "data": "bea4343c5d815cba55c6e1bcb835bcbea43432abc014f7b48a63....",
  "iv": "1aa8ebae81e116621251993df3b155d4"
}
```

<Note>Secret is used to decrypt the webhook payload.</Note>

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

<Steps>
  <Step title="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.

    <Card title="Go to register a webhook" icon="square-code" href="/v1/workflows/register-webhook" />
  </Step>

  <Step title="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 TypeScript Example theme={null}
    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 TypeScript Example theme={null}
    const ivBuffer = Buffer.from(iv, "hex");
    ```
  </Step>

  <Step title="Decryption">
    * Creates a decryptor object using the AES-256 algorithm in CBC (Cipher Block Chaining) mode, the key and the IV.

    ```typescript TypeScript Example theme={null}
    const decipher = crypto.createDecipheriv("aes-256-cbc", key, ivBuffer);
    ```

    * Start decrypting the data and store the result.

    ```typescript TypeScript Example theme={null}
    let decrypted = decipher.update(data, "hex", "utf8");
    decrypted += decipher.final("utf8");
    ```
  </Step>

  <Step title="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 TypeScript Example theme={null}
    const event = JSON.parse(decrypted);
    ```
  </Step>
</Steps>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.