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

# Register a 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 registering a new webhook.

### Requirements to start the flow.

<CardGroup cols={1}>
  <Card title="API key" icon="shield-keyhole">
    Have an API key ([Tutorial here](/quickstart#api-key-generation)).
  </Card>
</CardGroup>

### <Icon icon="arrow-progress" iconType="solid" /> Registration flow

<Steps>
  <Step title="Pick the type of webhook you need">
    The type goes in the URL path rather than the body, so you register one webhook per type. The available types are `orders`, for updates as an order moves through its lifecycle, `bank-accounts`, for changes to your registered bank accounts, and `users`, for changes to your users.
  </Step>

  <Step title="Register the endpoint">
    Send the address that should receive the events in the `url` field. Rio will send a POST request there every time an event of that type happens.

    ```json theme={null}
    {
      "url": "https://example.com/rio/webhooks/orders",
      "retryOnFailure": true
    }
    ```

    Setting `retryOnFailure` to `true` makes Rio retry a failed delivery up to 5 times with exponential backoff. If you leave it out, a failed delivery is only attempted once, so turn it on unless you have another way of catching missed events.

    <Card title="Go to Register a new webhook" icon="square-code" href="/v1/api-reference/webhooks/post-apiwebhooks">
      Register a new webhook to receive notifications about events in your account.
    </Card>
  </Step>

  <Step title="Save the secret">
    The response contains the `id` of the registration and a `secret`. Store the secret somewhere safe right away, because it is only returned by this call and cannot be read back later. If you lose it you have to delete the registration and create a new one.

    The payloads Rio sends are encrypted, and this secret is the key you decrypt them with.

    <Card title="Go to decrypt a webhook" icon="lock" href="/v1/workflows/decrypt-webhook" />
  </Step>

  <Step title="Check or change the registration later">
    You can list your registrations to confirm the URL and type are what you expect. Updating lets you point an existing registration at a new `url` or change `retryOnFailure`, and it keeps the same secret.

    <Card title="Go to get all webhook registrations" icon="square-code" href="/v1/api-reference/webhooks/get-apiwebhooks-1" />
  </Step>
</Steps>

### Webhook registration through the platform.

To register the webhook, you must log in to the platform, navigate to the webhooks section in your account settings, and save the secret once registered.

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