Subscribe to events from an event store

POST

/api/event-stores/{eventStoreName}/subscribe

Production

Creates a subscription to receive events from a specific event store.

Events will be delivered to the configured destination whenever new events matching your filter pattern are appended to streams in the event store.

Duplicate Detection

For webhook subscriptions, the system will automatically detect if a subscription with the same configuration already exists (same URL, headers, timeout, and event filter). If found, the existing subscription will be returned instead of creating a duplicate. This helps prevent accidentally creating multiple subscriptions for the same webhook endpoint.

Event Filtering

Events can be filtered using pattern matching:

* - Match ALL event types
namespace.* - Match all events in a namespace (e.g., user.* matches user.created, user.updated, etc.)
*.event - Match all events of a specific type across namespaces (e.g., *.created matches user.created, order.created, etc.)
namespace.event - Match a specific event type exactly (e.g., user.created)

Subscriber Types

Events can be delivered to several destination types:

Durable Object: Events are delivered to a Durable Object instance via its handle method
Webhook: Events are sent as HTTP POST requests to a specified URL
Queue: Events are sent to a Cloudflare Queue
Cloudflare Workflow: Events trigger a Cloudflare Workflow execution
WebSocket: Events are broadcast to connected WebSocket clients

Delivery Guarantees

At-least-once delivery (events may be delivered more than once in rare cases)
Events are delivered in the order they were appended to their respective streams
Failed deliveries are retried according to the configured retry policy

Authorizations

Bearer

Parameters

Path Parameters

eventStoreName

required

Event store name (e.g. “production”)

string

Event store name (e.g. “production”)

Request Body

object

eventFilter

required

Any of:

Match all event types

string

Allowed values: *

subscriberId

Optional custom ID for this subscription. If not provided, one will be generated.

string

subscriber

required

One of:

object

type

required

string

Allowed values: durable_object

config

required

Configuration for Durable Object subscribers

object

retryPolicy

Configuration for retry behavior

object

maxAttempts

required

Maximum number of delivery attempts before giving up

integer

backoffMinutes

required

How many minutes to wait between retry attempts

integer

namespace

required

The Durable Object namespace binding name in your worker

string

required

The ID of the Durable Object instance to deliver events to

string

initialPosition

The position in the message stream from which a consumer starts consuming messages when there is no prior checkpoint. Defaults to latest.

string

default: latest

Allowed values: latest earliest

Examples

Basic webhook subscription

{
  "eventFilter": "user.*",
  "subscriber": {
    "type": "webhook",
    "config": {
      "url": "https://example.com/webhooks/events",
      "headers": {
        "X-API-Key": "your-secret-key"
      },
      "retryPolicy": {
        "maxAttempts": 5,
        "backoffMinutes": 10
      }
    }
  }
}

Durable Object subscription

{
  "eventFilter": [
    "order.created",
    "order.updated"
  ],
  "subscriber": {
    "type": "durable_object",
    "config": {
      "namespace": "ORDER_PROCESSOR",
      "id": "order-processor-instance-1"
    }
  }
}

Cloudflare Workflow subscription

{
  "eventFilter": "*",
  "subscriber": {
    "type": "cloudflare_workflow",
    "config": {
      "bindingName": "EVENT_WORKFLOW"
    }
  }
}

WebSocket subscription for real-time updates

{
  "eventFilter": "notification.*",
  "subscriber": {
    "type": "websocket",
    "config": {
      "managerId": "notifications-websocket-manager"
    }
  }
}

Responses

200

Subscription created successfully. Use the returned subscriptionId to manage this subscription.

object

subscriptionId

required

Unique identifier for this subscription

string

status

required

Current status of the subscription

string

Allowed values: ACTIVE SUSPENDED ERROR INITIALIZING DELETED

statusDetails

Additional details about the current status

object

lastError

string

lastErrorAt

string format: date-time

retryCount

number

nextRetryAt

string format: date-time

eventStoreName

required

The event store name this subscription is connected to

string

eventFilter

required

The event pattern this subscription is filtering on

string

subscriberId

required

The ID of the subscriber

string

subscriberType

required

The type of subscriber to receive events

string

Allowed values: durable_object webhook queue cloudflare_workflow websocket

createdAt

required

When this subscription was created

string format: date-time

updatedAt

required

When this subscription was last updated

string format: date-time

lastProcessedEventGlobalPosition

The global position of the last successfully delivered event

number

isExistingSubscription

Whether this is an existing subscription that was found instead of creating a new one

boolean

message

Human-readable message about the subscription operation

string

Examples

New subscription created

{
  "subscriptionId": "sub_123456",
  "status": "ACTIVE",
  "eventStoreName": "production",
  "eventFilter": "user.*",
  "subscriberId": "webhook-user-events",
  "subscriberType": "webhook",
  "createdAt": "2023-10-25T15:30:45Z",
  "updatedAt": "2023-10-25T15:30:45Z",
  "lastProcessedEventGlobalPosition": 0,
  "isExistingSubscription": false,
  "message": "Successfully created new subscription (ID: webhook-user-events)."
}

Existing subscription found and returned

{
  "subscriptionId": "sub_789012",
  "status": "ACTIVE",
  "eventStoreName": "production",
  "eventFilter": "user.*",
  "subscriberId": "existing-webhook-user-events",
  "subscriberType": "webhook",
  "createdAt": "2023-10-20T10:15:30Z",
  "updatedAt": "2023-10-20T10:15:30Z",
  "lastProcessedEventGlobalPosition": 1234,
  "isExistingSubscription": true,
  "message": "Found existing webhook subscription with the same configuration (ID: existing-webhook-user-events). Returning existing subscription instead of creating a duplicate."
}

Existing subscription found but has errors

{
  "subscriptionId": "sub_345678",
  "status": "ERROR",
  "statusDetails": {
    "lastError": "Connection timeout",
    "lastErrorAt": "2023-10-25T14:30:00Z",
    "retryCount": 3
  },
  "eventStoreName": "production",
  "eventFilter": "user.*",
  "subscriberId": "error-webhook-user-events",
  "subscriberType": "webhook",
  "createdAt": "2023-10-25T14:00:00Z",
  "updatedAt": "2023-10-25T14:30:00Z",
  "lastProcessedEventGlobalPosition": 500,
  "isExistingSubscription": true,
  "message": "Found existing webhook subscription with the same configuration (ID: error-webhook-user-events), but it has errors. Consider fixing the configuration or check the error details."
}

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": "INVALID_CALLBACK_URL",
  "message": "The provided callback URL is invalid or not reachable",
  "details": {
    "callbackUrl": "https://example.com/webhooks/events"
  }
}

{
  "error": "INVALID_EVENT_FILTER",
  "message": "The provided event filter pattern is invalid",
  "details": {
    "eventFilter": "invalid..pattern",
    "validPatterns": [
      "*",
      "namespace.*",
      "*.event",
      "namespace.event"
    ]
  }
}

401

Unauthorized: Organization ID not found in authentication context

object

error

required

Error type

string

message

required

Human-readable error message

string

details

Additional error details

object

key

additional properties

nullable

Examples

{
  "error": "UNAUTHORIZED",
  "message": "Unauthorized"
}

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

Examples

{
  "error": "EVENT_STORE_NOT_FOUND",
  "message": "The specified event store does not exist",
  "details": {
    "eventStoreName": "nonexistent"
  }
}

500

Internal server error

object

error

required

Error type

string

message

required

Human-readable error message

string

details

Additional error details

object

key

additional properties

nullable