Manage webhooks in the UI

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.

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 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 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",
    "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:

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.

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.

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:

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

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

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.
4. On the Select events page, select the events you want to receive webhook notifications for, and select Continue.
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.
6. Select Submit to finish configuring your 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.
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.

Want to manage webhooks with the API instead? See Manage webhooks with the API.