Skip to content
delta-base docs

Connect to event store via WebSocket

GET
/api/event-stores/{eventStoreName}/events/ws

Establish a WebSocket connection to receive real-time events from an event store.

This endpoint implements the WebSocket protocol (RFC 6455) to provide a streaming connection of events. The HTTP connection is upgraded to a WebSocket connection, allowing for real-time bidirectional communication.

Connection Process:

  1. Connect to this endpoint using a WebSocket client (browser WebSocket API or library)
  2. The connection is upgraded from HTTP to WebSocket
  3. Events matching the filter will stream to the client in real-time
  4. The connection remains open until closed by either party

Event Filtering:

The filter query parameter accepts a JSON string that defines which events the client wants to receive. The filter can include:

  • type: Match specific event types (e.g., “user.created”)
  • streamId: Match events from specific streams
  • data: Match specific fields in the event data
  • metadata: Match specific fields in the event metadata

Example filters:

// Match user creation events
{
  "type": "user.created"
}

// Match events from a specific stream with metadata
{
  "streamId": "users-123",
  "metadata": {
    "source": "api"
  }
}

// Match events with specific data fields
{
  "type": "order.updated",
  "data": {
    "status": "completed"
  }
}

// Complex filter combining multiple criteria
{
  "type": "payment.processed",
  "streamId": "orders-456",
  "data": {
    "amount": 100
  },
  "metadata": {
    "region": "us-east"
  }
}

If no filter is provided, the client will receive all events. If there’s an error parsing the filter, the client will also receive all events (with an error logged).

Authentication:

  • Use the optional authToken parameter if authentication is required
  • Tokens should be obtained from your authentication system

Note: This endpoint is designed for WebSocket clients, not regular HTTP requests.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
eventStoreName
required

Event store name (automatically scoped to your organization)

string

Event store name (automatically scoped to your organization)

Query Parameters

Section titled “Query Parameters ”
clientId
required

Unique identifier for the client

string

Unique identifier for the client

authToken

Authentication token

string

Authentication token

filter

JSON string containing filter criteria for events. Can include type, streamId, data, and metadata matching.

string

JSON string containing filter criteria for events. Can include type, streamId, data, and metadata matching.

startPosition

Where to start receiving events from (defaults to “latest”)

string
Allowed values: latest beginning

Where to start receiving events from (defaults to “latest”)

Responses

Section titled “ Responses ”

101

Section titled “101 ”

Switching Protocols - WebSocket connection established

400

Section titled “400 ”

Invalid request parameters

object
error
required

Error type

string
message
required

Human-readable error message

string
details

Additional error details

object
key
additional properties
nullable
Examples
{
  "error": "MISSING_CLIENT_ID",
  "message": "A client ID is required"
}

401

Section titled “401 ”

Authentication failed

object
error
required

Error type

string
message
required

Human-readable error message

string
details

Additional error details

object
key
additional properties
nullable
Examples
{
  "error": "INVALID_AUTH_TOKEN",
  "message": "The provided authentication token is invalid or expired"
}

404

Section titled “404 ”

Event store not found

object
error
required

Error type

string
message
required

Human-readable error message

string
details

Additional error details

object
key
additional properties
nullable