Delivery Subscriptions API

The Delivery Subscriptions API provides a generalized subscription model for event delivery across multiple transport types. Each subscription declares which event types to receive, an optional payload filter, and a delivery configuration.

List Subscriptions

GET /api/delivery-subscriptions

Returns all delivery subscriptions scoped to the current application and environment.

Query Parameters:

Example:

GET /api/delivery-subscriptions?externalId=ext_system_abc

Response:

{
  "subscriptions": [
    {
      "id": "dsub_abc123",
      "applicationId": "app_abc123",
      "environment": "development",
      "events": ["session.status"],
      "filter": { "installSid": "AI_abc123" },
      "deliveryType": "webhook",
      "deliveryConfig": {
        "url": "https://example.com/webhook",
        "secret": "whsec_..."
      },
      "active": true,
      "externalId": "ext_system_abc",
      "createdAt": 1710000000000,
      "updatedAt": 1710000000000
    }
  ]
}

Get Subscription

GET /api/delivery-subscriptions/:id

Create Subscription

POST /api/delivery-subscriptions

Request Body:

{
  "events": ["session.status", "annotation.*"],
  "filter": {
    "installSid": "AI_abc123"
  },
  "deliveryType": "webhook",
  "deliveryConfig": {
    "url": "https://example.com/webhook",
    "secret": "whsec_your_secret"
  },
  "externalId": "ext_system_abc"
}

Delivery Configurations

Webhook:

{
  "deliveryType": "webhook",
  "deliveryConfig": {
    "url": "https://example.com/webhook",
    "secret": "whsec_your_secret"
  }
}

SQS:

{
  "deliveryType": "sqs",
  "deliveryConfig": {
    "queueUrl": "https://sqs.us-east-1.amazonaws.com/123456789/my-queue",
    "region": "us-east-1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "messageGroupId": "my-group"
  }
}

WebSocket (future):

{
  "deliveryType": "websocket",
  "deliveryConfig": {
    "channelPrefix": "events"
  }
}

Payload Filtering (Entity Key Filters)

The filter object limits delivery to events matching specific entity key values. This is the primary mechanism for tenant-scoped subscriptions — ensuring each subscriber only receives events relevant to their tenant/install/account.

{
  "filter": {
    "installSid": "AI_abc123",
    "proctorAccountLocationSid": "PA_xyz789"
  }
}

Matching rules:

• Every key in filter must be present in the event payload
• Every value must match (string coercion comparison — handles numeric/string mismatches from CDC data)
• Multiple keys use AND logic — all must match
• Subscriptions with no filter receive all matching events
• The in operator is supported for matching multiple possible values: { "status": { "in": ["active", "pending"] } }

Entity keys available for filtering are defined by the mapping's entityKeys array. These are the payload field names that identify the tenant/entity (e.g., installSid, proctorAccountLocationSid). When a mapping defines entity keys, CDC events include those values in the event payload, enabling O(1) subscription lookup via the Redis subscription index.

Redis Subscription Index (Performance)

When Redis is available, delivery subscriptions with entity key filters are indexed in a Redis hash structure that enables O(1) lookups per entity key value. Instead of scanning all active subscriptions in Postgres on every event, the dispatcher:

1. Extracts entity key values from the event payload
2. Looks up delivery:index:{applicationId}:{environment}:{entityKey}:{value} in Redis
3. Returns only subscriptions that match — no table scan

This is critical for high-throughput CDC pipelines where thousands of events per second need to be matched against potentially thousands of subscriptions.

If Redis is unavailable, the dispatcher falls back to a Postgres scan with in-memory filtering (correct but slower).

Update Subscription

PUT /api/delivery-subscriptions/:id

Request Body (all fields optional):

{
  "events": ["session.status"],
  "filter": { "installSid": "AI_new" },
  "deliveryConfig": {
    "url": "https://example.com/webhook-v2",
    "secret": "new_secret"
  },
  "externalId": "ext_updated"
}

Activate / Deactivate

POST /api/delivery-subscriptions/:id/activate
POST /api/delivery-subscriptions/:id/deactivate

Deactivated subscriptions stop receiving deliveries but are not deleted.

Delete Subscription

DELETE /api/delivery-subscriptions/:id