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:

In the top nav bar of the Ripple Custody UI, select Try beta version.
In the top right, select Settings > Event Distribution.
On the Event distribution page, under the Webhooks tab, select Add webhook.
On the Select events page, select the events you want to receive webhook notifications for, and select Continue.
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.
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:

In the top nav bar of the Ripple Custody UI, select Try beta version.
In the top right, select Settings > Event Distribution.
On the Event distribution page, under the Webhooks tab, select the webhook you want to edit.
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.