Manage webhooks with the API

Use this page to manage webhook channels with the Event Distribution Service (EDS) API. Webhooks push event notifications to an HTTPS endpoint that you control. To pull event history for reconciliation or audit workflows, see Manage events with the API.

Prepare the following values:

You must be a user with the eds-manager role to create and manage webhook channels for your domain.

You can subscribe to many event types when configuring a webhook. For detailed information about each event type and complete payload structures, see Event payload reference.

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.

When a subscribed event occurs, Ripple Custody sends a minimal event payload to your webhook URL. The callback body uses the event shape returned by the Events API and is designed for easy parsing.

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

For event-specific payload fields and event type names, see Event payload reference.

Call POST /v1/domains/{domainId}/channels to create a webhook channel.

curl -X POST "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @create-webhook-channel.json

The request body uses the EDS_WebhookChannelCreate schema:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "My Webhook Channel",
  "supportedEventTypes": [
    "IntentCreated",
    "IntentUpdated",
    "IntentClosed"
  ],
  "createdBy": "b7c8d9e0-f1a2-3456-bcde-f23456789012",
  "type": "WEBHOOK",
  "url": "https://your-domain.com/webhook-endpoint"
}

The API returns the created channel:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domainId": "25aaec0d-e8dc-44b6-8070-9231f1ddadf0",
  "name": "My Webhook Channel",
  "supportedEventTypes": [
    "IntentCreated",
    "IntentUpdated",
    "IntentClosed"
  ],
  "type": "WEBHOOK",
  "status": "ACTIVE",
  "maxRetries": 3,
  "url": "https://your-domain.com/webhook-endpoint",
  "createdBy": "b7c8d9e0-f1a2-3456-bcde-f23456789012",
  "lastUpdatedBy": "b7c8d9e0-f1a2-3456-bcde-f23456789012",
  "createdAt": "2025-03-07T14:22:37.389Z",
  "lastUpdatedAt": "2025-03-07T14:22:37.389Z",
  "errorRate": 0
}

Call GET /v1/domains/{domainId}/channels to retrieve all webhook channels for a domain.

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

The response is an array of channel objects.

Call GET /v1/domains/{domainId}/channels/{channelId} to retrieve one webhook channel.

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

The response is a channel object.

Call PATCH /v1/domains/{domainId}/channels/{channelId} to update a webhook channel. Include only the fields you need to change.

curl -X PATCH "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d @update-webhook-channel.json

The request body uses the EDS_ChannelUpdate schema:

{
  "name": "Operations Webhook Channel",
  "supportedEventTypes": [
    "IntentCreated",
    "IntentUpdated",
    "IntentClosed"
  ],
  "status": "active",
  "maxRetries": 3,
  "lastUpdatedBy": "b7c8d9e0-f1a2-3456-bcde-f23456789012"
}

The API returns the updated channel object.

Call POST /v1/domains/{domainId}/channels/{channelId}/test to test a webhook channel. The operation does not define a request body.

curl -X POST "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}/test" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

The API returns 200 OK when the test request is accepted.

Call DELETE /v1/domains/{domainId}/channels/{channelId} to delete a webhook channel. The operation does not define a request body.

curl -X DELETE "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

The API returns 200 OK when the channel is deleted.

EDS delivery events are operational records for webhook delivery attempts. They are different from the event payload sent to your webhook endpoint.

List all delivery events across channels:

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/events" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

List delivery events for one channel:

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}/events" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Get one delivery event:

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/channels/${CHANNEL_ID}/events/${EVENT_ID}" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Delivery event list operations return an array of EDS_Event objects. The delivery event detail operation returns one EDS_Event object.

{
  "id": "c0c54215-77e8-4e8f-8b0f-b3d60269f2f7",
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "channelName": "My Webhook Channel",
  "type": "IntentCreated",
  "status": "FAILED",
  "createdAt": "2025-03-07T14:22:37.389Z",
  "lastUpdatedAt": "2025-03-07T14:22:40.889Z",
  "retriedCount": 3,
  "payload": "{\"id\":\"35e4d8d9-f943-484b-865c-c736679ba0cc\",\"type\":\"IntentCreated\"}"
}

If a webhook delivery fails, for example if your endpoint is unavailable or returns an error, Ripple Custody retries delivery using exponential backoff.

1. Ripple Custody sends the event to your webhook endpoint.
2. If delivery fails, the system waits and retries using exponential backoff.
3. After the maximum number of retry attempts is exhausted, the delivery event is marked as FAILED and automatic retries stop.

The default retry behavior is:

With the default values, if delivery fails, the system retries after 500 ms, then 1000 ms, then 2000 ms.

If your endpoint does not respond within the timeout period, the delivery is considered failed and is retried.

Webhook deliveries are not rate-limited by default. Design your endpoint to handle:

• Multiple concurrent webhook deliveries.
• Bursts of events during high activity periods.
• Retry attempts for failed deliveries.

If your endpoint cannot keep up with event volume, consider:

• Implementing a queue to buffer incoming webhooks.
• Scaling your webhook receiver horizontally.
• Using AMQP queues instead for guaranteed delivery and backpressure handling.

Use EDS delivery events, the Events API, and any configured AMQP integration when recovering from webhook delivery failures:

1. Check delivery event records for FAILED status.
2. Use retriedCount and lastUpdatedAt to understand retry activity.
3. Use List events with sortBy=sequenceNumber to reconcile the event history your system processed.
4. Page through Events API results with startingAfter; the Events API schema does not define time-range filters.
5. If your deployment includes an AMQP queue integration, inspect the queue to recover missed events. Contact Ripple support for help with AMQP-based recovery.
6. Process any missing event IDs or sequence numbers in your integration.

Secure the endpoint that receives webhook callbacks:

• Use HTTPS endpoints.
• Validate incoming requests.
• Implement authentication or authorization for your receiver.
• Use IP allowlisting if required by your environment.

Want to manage webhooks with the UI instead? See Manage webhooks in the UI.