Events

The Events API lets you retrieve your event history, inspect individual events, and filter by delivery state. All endpoints require a valid JWT session token.

List events

Returns a paginated list of all events for your account, ordered by ingestion time (newest first).

GET /v1/events

Authentication

Authorization: Bearer <jwt>

Query parameters

Parameter	Type	Default	Maximum	Description
`page`	integer	`0`	—	Zero-indexed page number
`size`	integer	`20`	`1000`	Number of events per page

Example

curl "https://api.eldrstream.com/v1/events?page=0&size=50" \
  -H "Authorization: Bearer <jwt>"

Response

{
  "events": [
    {
      "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
      "tenantId": "a3f8bc1d2e",
      "state": "DELIVERED",
      "ingestionTimestamp": "2025-01-15T10:30:00Z",
      "targetWebhook": "https://example.com/hooks/eldrstream",
      "errorReason": null,
      "originalPayload": {
        "event_type": "order.created",
        "order_id": "ORD-1001"
      }
    }
  ],
  "total": 142
}

Field	Description
`events`	Array of event objects for the current page
`total`	Total number of events in your account

Event object fields

Field	Type	Description
`eventId`	string	Unique event identifier
`tenantId`	string	Your tenant ID
`state`	string	`DELIVERED` or `FAILED`
`ingestionTimestamp`	ISO 8601	When EldrStream received the event
`targetWebhook`	string	The webhook URL the event was dispatched to
`errorReason`	string \| null	Human-readable failure reason, if applicable
`originalPayload`	object \| null	The original payload you sent

Get a single event

Returns all event records associated with a specific event ID. If the same event was delivered to multiple webhook endpoints, each delivery appears as a separate entry.

GET /v1/events/{id}

Path parameters

Parameter	Description
`id`	The `eventId` returned when the event was ingested

Example

curl "https://api.eldrstream.com/v1/events/evt_01J8ZXQY5H4KCZP3M2R..." \
  -H "Authorization: Bearer <jwt>"

Response

[
  {
    "eventId": "evt_01J8ZXQY5H4KCZP3M2R...",
    "tenantId": "a3f8bc1d2e",
    "state": "DELIVERED",
    "ingestionTimestamp": "2025-01-15T10:30:00Z",
    "targetWebhook": "https://example.com/hooks/eldrstream",
    "errorReason": null,
    "originalPayload": {
      "event_type": "order.created",
      "order_id": "ORD-1001"
    }
  }
]

Status codes

Status	Meaning
`200 OK`	Event found
`404 Not Found`	No event with that ID in your account

List events by state

Returns a paginated list of events filtered by delivery state.

GET /v1/events/state/{state}

Path parameters

Parameter	Values	Description
`state`	`DELIVERED`, `FAILED`	The delivery state to filter by

Query parameters

Parameter	Type	Default	Maximum	Description
`page`	integer	`0`	—	Zero-indexed page number
`size`	integer	`20`	`1000`	Number of events per page

Example — list all failed events

curl "https://api.eldrstream.com/v1/events/state/FAILED?page=0&size=100" \
  -H "Authorization: Bearer <jwt>"

Response

{
  "events": [
    {
      "eventId": "evt_01J8AABB2C...",
      "tenantId": "a3f8bc1d2e",
      "state": "FAILED",
      "ingestionTimestamp": "2025-01-14T08:12:44Z",
      "targetWebhook": "https://example.com/hooks/eldrstream",
      "errorReason": "HTTP 503 from https://example.com/hooks/eldrstream",
      "originalPayload": { "event_type": "shipment.dispatched" }
    }
  ],
  "total": 3
}

​Events

​List events

​Authentication

​Query parameters

​Example

​Response

​Event object fields

​Get a single event

​Path parameters

​Example

​Response

​Status codes

​List events by state

​Path parameters

​Query parameters

​Example — list all failed events

​Response

Events

List events

Authentication

Query parameters

Example

Response

Event object fields

Get a single event

Path parameters

Example

Response

Status codes

List events by state

Path parameters

Query parameters

Example — list all failed events

Response