Manage events with the API

Use this page to retrieve Ripple Custody event history with the Events API. Events are immutable records generated by user actions, system signals, and ledger updates. You can list events for a domain, page through event history, and use the results for reconciliation or audit workflows.

You cannot create, update, or delete events directly with the Events API. To configure push delivery to your systems, see Manage webhooks with the API.

Event actions

Action	API procedure	API reference
List events	List events	List events
Page through event history	Page through event history	List events
Include subdomain events	Choose the event scope	List events
Configure webhook delivery	Manage webhooks with the API	Create a channel

For event-specific payload fields, see Event payload reference. Before calling the API, see Authenticate API requests.

Event tracking methods

Ripple Custody supports pull and push event tracking methods:

Method	Type	Best for	Setup required
Events API	Pull	Reconciliation, historical queries, on-demand event retrieval	None
Webhooks	Push	Real-time notifications and event-driven workflows	Configure webhook channels
AMQP queue	Push	High-volume event processing and external queue integration	Contact Ripple support

Use webhooks for real-time notifications and use the Events API for periodic reconciliation. The Events API gives you an independent pull-based view of event history.

Configure webhook delivery

The Event Distribution Service (EDS) lets you configure how Ripple Custody pushes events to your systems. The EDS API currently supports webhook channels.

To set up webhook delivery:

Ensure you have the eds-manager role for your domain.
Obtain a JWT token. See Authenticate API requests.
Set up an HTTPS endpoint to receive webhook notifications.
Create a webhook channel. See Create a webhook channel.
Test your integration. See Test a webhook channel.
Implement reconciliation with the Events API.

List events

Call GET /v1/domains/{domainId}/events to list events in a domain.

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/events?limit=100&sortBy=sequenceNumber&sortOrder=DESC" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Query parameters

Parameter	Location	Required	Type	Description
`domainId`	Path	Yes	string, UUID	Unique identifier for the domain.
`limit`	Query	No	integer, 1-100	Number of events to return.
`startingAfter`	Query	No	string, UUID	Cursor used to determine the beginning of query results.
`sortBy`	Query	No	string	Property used to sort results. The supported value is `sequenceNumber`.
`sortOrder`	Query	No	string	Sort order. Supported values are `ASC` and `DESC`.
`scope`	Query	No	string	Event scope. Supported values are `Self` and `SelfAndDescendants`. The default is `Self`.

The response is an events collection:

{
  "items": [
    {
      "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"
    }
  ],
  "count": 1,
  "nextStartingAfter": "03424a3f-bdfc-4521-b8b2-933a8ff13cce"
}

Response fields

Field	Description
`items`	Array of event records.
`count`	Number of event records in the response.
`currentStartingAfter`	Cursor used for the current page, when provided.
`nextStartingAfter`	Cursor to use as `startingAfter` for the next page, when more results are available.

Each event in items contains:

Field	Description
`domainId`	Domain where the event was generated.
`payload`	Event-specific payload. The payload includes a `type` discriminator.
`id`	Unique event ID.
`sequenceNumber`	Event sequence number. Sequence numbers are strictly increasing, but may not be contiguous.
`savedAt`	Timestamp when the event was saved.

For event-specific payload fields, see Event payload reference.

Page through event history

Use nextStartingAfter from one response as the startingAfter value in the next request:

curl -X GET "${CUSTODY_API_URL}/v1/domains/${DOMAIN_ID}/events?limit=100&startingAfter=${NEXT_STARTING_AFTER}&sortBy=sequenceNumber&sortOrder=ASC" \
  -H "Authorization: Bearer ${JWT_TOKEN}"

Use sortBy=sequenceNumber when you need deterministic event ordering. Use sortOrder=ASC to process older events before newer events, or sortOrder=DESC to retrieve the latest events first.

Choose the event scope

By default, the Events API returns events for the requested domain only:

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

To include events from the requested domain and its subdomains, use scope=SelfAndDescendants:

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

Reconcile event delivery

Use the Events API as the source for pull-based reconciliation:

Store the last processed event ID or sequence number in your integration.
Poll List events with sortBy=sequenceNumber.
Page with startingAfter until there are no additional events.
Compare the returned event IDs or sequence numbers with the events your system processed from webhooks or AMQP.
Retrieve entity details with the relevant API when an event payload only identifies the changed entity.

Want to manage events in the UI instead? See Manage events in the UI.