# Webhooks

**Note**

Access to webhook configuration is currently available through the beta version of the Ripple Custody beta UI. Though you access it through the beta UI, the webhook functionality is production-ready and available through the API as well.

**Enabling the feature**

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.

The v1.19 release of the Ripple Custody beta UI introduces support for event distribution through webhooks.
Webhooks are lightweight HTTP callbacks that allow real-time delivery of event notifications to your systems.

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.

## Event payload

Event payloads are minimal and designed for easy parsing.

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


```
    {
        "domainId": "25aaec0d-e8dc-44b6-8070-9231f1ddadf0", // The unique identifier of the domain where the event originated
        "id": "03424a3f-bdfc-4521-b8b2-933a8ff13cce",       // The ID of the webhook notification
        "payload": {                                        // Event payload
            "id": "35e4d8d9-f943-484b-865c-c736679ba0cc",   // The ID of the event
            "type": "IntentCreated"                         // The type of event
        },
        "savedAt": "2025-03-07T14:22:37.389Z",              // The time when the webhook notification was sent
        "sequenceNumber": 369                               // 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, Ripple Custody will automatically attempt retries.

## 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.7d10b72f.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.7d10b72f.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.7d10b72f.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.7d10b72f.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.7d10b72f.png)