# 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](/products/custody/operations-and-maintenance/events-and-webhooks/webhooks-api).

## Event actions

| Action | API procedure | API reference |
|  --- | --- | --- |
| List events | [List events](#list-events) | [List events](/products/custody/reference/api/openapi/events/getevents) |
| Page through event history | [Page through event history](#page-through-event-history) | [List events](/products/custody/reference/api/openapi/events/getevents) |
| Include subdomain events | [Choose the event scope](#choose-the-event-scope) | [List events](/products/custody/reference/api/openapi/events/getevents) |
| Configure webhook delivery | [Manage webhooks with the API](/products/custody/operations-and-maintenance/events-and-webhooks/webhooks-api) | [Create a channel](/products/custody/reference/api/openapi/event-distribution-service/createchannel) |


For event-specific payload fields, see [Event payload reference](/products/custody/reference/events-and-webhooks/event-payload-reference). Before calling the API, see [Authenticate API requests](/products/custody/identity-and-access/authentication/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](/products/custody/support/get-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:

1. Ensure you have the `eds-manager` role for your domain.
2. Obtain a JWT token. See [Authenticate API requests](/products/custody/identity-and-access/authentication/authenticate-api-requests).
3. Set up an HTTPS endpoint to receive webhook notifications.
4. Create a webhook channel. See [Create a webhook channel](/products/custody/operations-and-maintenance/events-and-webhooks/webhooks-api#create-a-webhook-channel).
5. Test your integration. See [Test a webhook channel](/products/custody/operations-and-maintenance/events-and-webhooks/webhooks-api#test-a-webhook-channel).
6. Implement reconciliation with the Events API.


## List events

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


```sh
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:


```json
{
  "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](/products/custody/reference/events-and-webhooks/event-payload-reference).

## Page through event history

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


```sh
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:


```sh
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`:


```sh
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:

1. Store the last processed event ID or sequence number in your integration.
2. Poll [List events](/products/custody/reference/api/openapi/events/getevents) with `sortBy=sequenceNumber`.
3. Page with `startingAfter` until there are no additional events.
4. Compare the returned event IDs or sequence numbers with the events your system processed from webhooks or AMQP.
5. 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](/products/custody/operations-and-maintenance/events-and-webhooks/events-ui).