# Manage webhooks in the UI

The webhooks feature must be enabled using a feature flag on your Ripple Custody instance. Contact your Ripple liaison if you're unable to access the feature by performing the steps in the following section.

Webhooks are lightweight HTTP callbacks that allow real-time delivery of event notifications to your systems. Use this page to manage webhook channels in the Ripple Custody beta UI.

You can select from a wide range of events that you want to subscribe to and configure a webhook URL. Once you complete the setup, Ripple Custody will automatically send minimal event payloads to your registered endpoint when the selected events occur.

## Available event types

You can subscribe to many event types when configuring a webhook. For detailed information about each event type and complete payload structures, see [Event tracking](/products/custody/v1.36/reference/events-and-webhooks/event-payload-reference) for a complete list.

For intent state changes, subscribe to `IntentUpdated` to receive updates when an intent is approved or rejected. Subscribe to `IntentClosed` to receive updates when an intent reaches its final state.

## Event payload

Event payloads are minimal and designed for easy parsing.

The following sample shows a typical payload for an intent creation event:


```json
{
    "domainId": "25aaec0d-e8dc-44b6-8070-9231f1ddadf0",
    "id": "03424a3f-bdfc-4521-b8b2-933a8ff13cce",
    "payload": {
        "id": "35e4d8d9-f943-484b-865c-c736679ba0cc",
        "type": "IntentCreated"
    },
    "savedAt": "2025-03-07T14:22:37.389Z",
    "sequenceNumber": 369
}
```

**Payload fields:**

| Field | Description |
|  --- | --- |
| `domainId` | The unique identifier of the domain where the event originated |
| `id` | The ID of the webhook notification |
| `payload.id` | The ID of the event |
| `payload.type` | The type of event (e.g., `IntentCreated`, `IntentUpdated`) |
| `savedAt` | The timestamp when the webhook notification was sent |
| `sequenceNumber` | The sequence in which this event occurred |


## Securing your webhook endpoint

Make sure your webhook endpoint is properly secured to prevent unauthorized access. Validating incoming requests and using HTTPS are just a few ways in which you can secure your endpoints.

## Delivery retries

If a webhook delivery fails (for example, if your endpoint is down or returns an error), Ripple Custody automatically retries delivery using an **exponential backoff** strategy.

### How it works

1. **Initial delivery attempt** — Ripple Custody sends the event to your webhook endpoint.
2. **Retry on failure** — If delivery fails, the system waits and retries using exponential backoff.
3. **Maximum retries** — After the maximum number of retry attempts is exhausted, the event delivery status is marked as `FAILED` and automatic retries stop.


The retry mechanism uses exponential backoff with the following default parameters:

| Parameter | Default | Description |
|  --- | --- | --- |
| Max retries | 3 | Number of retry attempts before marking as `FAILED` |
| Initial interval | 500 ms | Wait time before the first retry |
| Multiplier | 2 | Factor applied to increase wait time between retries |
| Max interval | 5000 ms | Upper limit for wait time between retries |


**Example with defaults**: If delivery fails, the system retries after 500 ms, then 1000 ms, then 2000 ms (capped at 5000 ms if exceeded).

Retry parameters are configured at the instance level and require coordination with Ripple teams to modify. Contact your Ripple partner engineer if you need to adjust retry behavior for your deployment.

### Handling failed deliveries

If webhook delivery fails after all retries are exhausted, you have two options to recover missed events:

| Recovery method | Description |
|  --- | --- |
| **Events API** | Use the [List events](/products/custody/v1.36/reference/api/openapi/events/getevents) API to retrieve events that occurred during the downtime. Filter by time range or sequence number to identify missed events. |
| **AMQP queue** | If your deployment includes an AMQP queue integration, you can inspect the queue to recover missed events. Contact [Ripple support](/products/custody/v1.36/support/get-support) for assistance with AMQP-based recovery. |


**Best practice**: Implement a reconciliation process that periodically calls the Events API to verify your system has received all expected events. This provides a safety net for any delivery failures.

## Register a webhook

Prerequisite
You must be a user with the role `eds-manager` to create and manage webhooks for your domain.

To register a webhook:

1. In the top nav bar of the Ripple Custody UI, select **Try beta version**.
2. In the top right, select **Settings > Event Distribution**.
3. On the **Event distribution** page, under the **Webhooks** tab, select **Add webhook**.
![Add webhook](/assets/custody-add-webhook.0902a736663ef0905333643ea514188cb9e69284fd1c4eec95166ccb9c9919ea.cb5b5c2c.png)
4. On the **Select events** page, select the events you want to receive webhook notifications for, and select **Continue**.
![Select events](/assets/select-webhook-events.5aea07d7e88f3dfdf5d2d879a4217bcea9348c8d7fcadd7e6600a114faede529.cb5b5c2c.png)
5. In the **Configure channel** step, enter the webhook endpoint information:
  1. In the **Endpoint name** field, enter a descriptive name for the webhook you're creating.
  2. In the **Endpoint URL** field, enter the webhook URL where you want to receive the event information.
![Register webhook](/assets/register-webhook.34f9296fe3ad28844d50bdaf61b8ed81eb551317c64ed29d724051124f6e3d56.cb5b5c2c.png)
6. Select **Submit** to finish configuring your webhook.


Your webhook is successfully set up when you see a message at the bottom of your screen indicating that your webhook was created.

## Update an existing webhook

To update an existing webhook:

1. In the top nav bar of the Ripple Custody UI, select **Try beta version**.
2. In the top right, select **Settings > Event Distribution**.
3. On the **Event distribution** page, under the **Webhooks** tab, select the webhook you want to edit.
![Select webhook to edit](/assets/select-webhook-to-edit.a2b2994f25c4b950e2e6a296865b88de5c9cd257f2863fbcfd3448d4f617331e.cb5b5c2c.png)
4. Select the action you want to take:
  * Edit the list of events that you've subscribed: Select **Edit webhook**.
  * Send a test event, change the webhook's active status, or delete the webhook: Select the overflow menu and select the desired option.
![Edit webhook](/assets/edit-webhook.9f359cc4e8b95dff8feac211a7d1e9a1b115f848ad93bcf2ab6444e013500720.cb5b5c2c.png)


Want to manage webhooks with the API instead? See [Manage webhooks with the API](/products/custody/v1.36/operations-and-maintenance/events-and-webhooks/webhooks-api).