Events Rail

Events Rail

Event distribution, pub/sub, and event sourcing.

Overview

The Events Rail provides endpoints for event distribution, subscription management, and event replay capabilities.

Base URL

/api/v1/events

Endpoints

List Events

GET /api/v1/events

List events for the tenant.

Query Parameters:

Parameter	Type	Description
type	string	Filter by event type
entityType	string	Filter by entity type
entityId	string	Filter by entity ID
from	string	Start timestamp
to	string	End timestamp
page	number	Page number
perPage	number	Items per page

Response:

{
  "data": [
    {
      "eventId": "evt_abc123",
      "type": "contract.created",
      "schemaVersion": "1.0.0",
      "occurredAt": "2025-01-15T10:00:00Z",
      "producer": "contracts",
      "entity": {
        "type": "contract",
        "id": "con_xyz"
      },
      "payload": {
        "contractType": "MURABAHA",
        "status": "DRAFT"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "total": 1500
  }
}

Get Event

GET /api/v1/events/:eventId

Get event details.

Replay Events

POST /api/v1/events/replay

Replay events to a webhook endpoint.

Request Body:

{
  "webhookId": "wh_abc123",
  "filter": {
    "type": "contract.*",
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-15T00:00:00Z"
  },
  "batchSize": 100
}

Response:

{
  "data": {
    "replayId": "rpl_xyz",
    "status": "IN_PROGRESS",
    "totalEvents": 1500,
    "processedEvents": 0,
    "startedAt": "2025-01-15T10:00:00Z"
  }
}

Get Replay Status

GET /api/v1/events/replay/:replayId

Get replay job status.

Subscribe to Events

POST /api/v1/events/subscriptions

Create an event subscription (internal).

Request Body:

{
  "name": "Contract Processor",
  "eventTypes": ["contract.*"],
  "endpoint": "internal://contract-processor",
  "filterExpression": "payload.status == 'ACTIVE'"
}

List Subscriptions

GET /api/v1/events/subscriptions

List event subscriptions.

Get Event Schema

GET /api/v1/events/schemas/:eventType

Get JSON schema for an event type.

Response:

{
  "data": {
    "eventType": "contract.created",
    "version": "1.0.0",
    "schema": {
      "type": "object",
      "properties": {
        "contractId": { "type": "string" },
        "contractType": { "type": "string" },
        "status": { "type": "string" }
      },
      "required": ["contractId", "contractType"]
    }
  }
}

List Event Types

GET /api/v1/events/types

List all available event types.

Response:

{
  "data": [
    {
      "type": "contract.created",
      "description": "Contract created",
      "producer": "contracts",
      "schemaVersion": "1.0.0"
    },
    {
      "type": "contract.activated",
      "description": "Contract activated",
      "producer": "contracts",
      "schemaVersion": "1.0.0"
    }
  ]
}

Event Envelope

All events follow the standard envelope format:

{
  "event_id": "evt_abc123",
  "event_type": "contract.created",
  "schema_version": "1.0.0",
  "occurred_at": "2025-01-15T10:00:00Z",
  "producer": "contracts",
  "trace_id": "trace_xyz",
  "entity": {
    "type": "contract",
    "id": "con_123"
  },
  "payload": {},
  "term_ids": ["term_murabaha"],
  "correlation_id": "corr_abc",
  "metadata": {}
}

Event Categories

Category	Examples
Contract	contract.created, contract.activated
KYC	kyc.verified, kyc.expired
Compliance	compliance.alert.created
Payment	payment.completed, payment.failed
System	system.health_check

See Also

• Webhooks Rail - Event delivery
• Event Catalog - Complete event list