Event Bus REST API Reference

Event Bus REST API reference. 15 endpoints: publish, batch publish, topic config, subscription management, consumer position, DLQ operations, and replay. Apache Kafka (domain events) + RabbitMQ (transactional tasks). Protobuf schemas, tenant isolation, RBAC manifest enforcement.

The Event Bus is the asynchronous backbone of the platform. It provides Pub/Sub via Apache Kafka for domain events (clicks, conversions, payouts) and RabbitMQ for transactional tasks (notifications, payments). All event schemas are defined in Protobuf and enforced via Buf CLI backward-compatibility checks on every PR.

See the REST API Overview for authentication, error format, pagination, and rate limiting.

For layout brevity, the /api/v1 base path prefix is omitted from the endpoint tables below.

Endpoints

Endpoint	Auth	Description
`POST /events/publish`	✅	Publish a single event
`POST /events/publish/batch`	✅	Batch publish (up to 500 events)
`GET /events/topics`	✅	List available topics
`GET /events/topics/:topic/schema`	✅	Topic Protobuf schema + version
`GET /events/topics/:topic/config`	✅	Topic config (retention, partitions)
`GET /events/subscriptions`	✅	List active subscriptions for module
`POST /events/subscriptions`	✅	Register a subscription
`DELETE /events/subscriptions/:id`	✅	Unsubscribe
`GET /events/subscriptions/:id/position`	✅	Consumer position (offset + lag)
`POST /events/subscriptions/:id/seek`	✅	Replay — seek to timestamp
`GET /events/dlq`	✅	Dead Letter Queue — list failed
`GET /events/dlq/:id`	✅	DLQ event details
`POST /events/dlq/:id/retry`	✅	Retry a single DLQ event
`POST /events/dlq/replay-all`	✅	Replay all `pending` DLQ events
`DELETE /events/dlq/:id`	✅	Mark DLQ event as resolved

POST /api/v1/events/publish — Publish Event

POST https://api.septemcore.com/v1/events/publish
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "topic":     "platform.module.events",
  "type":      "module.registry.activated",
  "payload":   { "moduleId": "crm-v2" },
  "schemaVersion": "1.0.0"
}

Response 202 Accepted (fire-and-forget — Kafka publish is async):

{
  "eventId":   "01j9pevt0000000000000001",
  "topic":     "platform.module.events",
  "type":      "module.registry.activated",
  "status":    "queued",
  "createdAt": "2026-04-22T04:10:00Z"
}

Event Object

Field	Type	Description
`eventId`	`string` (UUID v7)	Unique event ID — used for idempotency dedup
`type`	`string`	Event type in `domain.entity.verb` format
`source`	`string`	Publishing module ID (injected by Gateway, not trusted from client)
`tenantId`	`string`	Injected by Gateway from JWT — cannot be set by caller
`payload`	`object`	Event payload (max 1 MB; use Claim Check pattern for larger data)
`schemaVersion`	`string` (semver)	Protobuf schema version
`traceId`	`string`	OpenTelemetry trace ID
`timestamp`	`string` (ISO 8601)	Event creation time

Publish RBAC

A module can only publish events declared in manifest.events.publishes[]. Attempting to publish an undeclared event returns 403 Forbidden. Kernel-owned events (auth.*, money.*, billing.*) can only be published by kernel services — module attempts are always rejected.

POST /api/v1/events/publish/batch — Batch Publish

POST https://api.septemcore.com/v1/events/publish/batch
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "topic": "platform.module.events",
  "events": [
    { "type": "module.registry.activated", "payload": { "moduleId": "crm-v2" } },
    { "type": "module.registry.deactivated", "payload": { "moduleId": "old-crm" } }
  ]
}

Limit	Value
Max events per batch	500
Max payload per event	1 MB
Exceeded	`400 Bad Request` (`problems/batch-limit-exceeded`)

GET /api/v1/events/topics — List Topics

Lists all Kafka topics available to the current module (filtered by manifest events.subscribes[] declaration):

{
  "data": [
    {
      "topic":      "platform.auth.events",
      "domain":     "auth",
      "partitions": 12,
      "retention":  "168h",
      "examples":   ["auth.user.created", "auth.user.logged_in"]
    },
    {
      "topic":      "platform.money.events",
      "domain":     "money",
      "partitions": 12,
      "retention":  "168h",
      "examples":   ["money.wallet.credited", "money.wallet.debited"]
    }
  ],
  "next_page_token": ""
}

Kafka Topic Naming Convention

Parameter	Value
Pattern	`platform.<domain>.events` — one topic per bounded context
Partition key	`entityId` — all events for one entity land on the same partition (ordering guarantee)
Cross-entity ordering	Not guaranteed — events for entity A and B on different partitions may arrive out of relative order
Default retention	7 days (`KAFKA_RETENTION_HOURS=168`)
Audit topic retention	30 days (`KAFKA_AUDIT_RETENTION_HOURS=720`) — extended for compliance
Max payload	1 MB (`message.max.bytes`)

Platform Topics Catalogue

Topic	Domain	Example events
`platform.auth.events`	IAM	`auth.user.created`, `auth.user.logged_in`, `auth.role.changed`
`platform.module.events`	Module Registry	`module.registry.registered`, `module.registry.activated`
`platform.money.events`	Money Service	`money.wallet.credited`, `money.wallet.debited`
`platform.files.events`	File Storage	`files.file.uploaded`
`platform.notify.events`	Notify Service	`notify.notification.sent`
`platform.audit.events`	Audit Service	`audit.record.created`
`platform.billing.events`	Billing	`billing.plan.changed`, `billing.subscription.changed`
`platform.data.events`	Data Layer (CDC)	CDC events via Debezium

GET /api/v1/events/topics/:topic/schema — Topic Schema

Returns the current Protobuf schema for a topic and its semver version:

{
  "topic":          "platform.money.events",
  "schemaVersion":  "2.1.0",
  "protoDefinition": "syntax = \"proto3\";\n\nmessage MoneyEvent {\n  string event_id = 1;\n  ...\n}",
  "breakingChangesPolicy": "buf breaking (FILE) enforced on every PR"
}

POST /api/v1/events/subscriptions — Register Subscription

POST https://api.septemcore.com/v1/events/subscriptions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "topic":         "platform.money.events",
  "consumerGroup": "notify.money-handler",
  "handlerName":   "money-handler"
}

Consumer groups follow the naming convention <service>.<handler-name>.

A module can only subscribe to topics declared in manifest.events.subscribes[]. Attempting to subscribe to an undeclared topic returns 403 Forbidden. An empty (or absent) subscribes field in the manifest means zero allowed subscriptions.

GET /api/v1/events/subscriptions/:id/position — Consumer Position

{
  "subscriptionId": "sub_01j9p000000001",
  "topic":          "platform.money.events",
  "consumerGroup":  "notify.money-handler",
  "partitions": [
    { "partition": 0, "currentOffset": 10450, "logEndOffset": 10450, "lag": 0 },
    { "partition": 1, "currentOffset": 9200,  "logEndOffset": 9250,  "lag": 50 }
  ],
  "totalLag": 50
}

Consumer Lag Alert Thresholds

Lag level	Action
`> 1 min`	`info` — logged only
`> 5 min`	`warning` — Notify sent to tenant-admin
`> 15 min`	`critical` — Notify + PagerDuty
Bulk-import spike detected	Warnings suppressed for 30 minutes to prevent false alerts

POST /api/v1/events/subscriptions/:id/seek — Replay from Timestamp

Seeks a consumer group to a specific point in time, enabling event replay:

POST https://api.septemcore.com/v1/events/subscriptions/sub_01j9p000000001/seek
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "seekTo": "2026-04-20T00:00:00Z"
}

Response 202 Accepted.

Kafka stores events for KAFKA_RETENTION_HOURS (default 168 h = 7 days). Seeking beyond the retention window returns 422 Unprocessable Entity (problems/events.retention.exceeded).

Dead Letter Queue (DLQ)

Events that fail processing 3 times in a row (poison message) are moved to the dead-letter topic platform.{domain}.dlq and removed from the main consumer stream — the consumer continues processing subsequent events.

GET /api/v1/events/dlq — List DLQ Events

GET https://api.septemcore.com/v1/events/dlq
  ?topic=platform.money.events
  &status=pending
  &page_size=20
Authorization: Bearer <access_token>

DLQ event object:

{
  "id":          "dlq_01j9p000000001",
  "eventId":     "01j9pevt0000000000000005",
  "topic":       "platform.money.events",
  "type":        "money.wallet.credited",
  "payload":     { "txId": "tx_001", "amountCents": 5000 },
  "failureCount": 3,
  "lastError":   "consumer timeout after 30s",
  "status":      "pending",
  "createdAt":   "2026-04-21T10:00:00Z"
}

DLQ status	Meaning
`pending`	Failed, awaiting manual retry or replay-all
`resolved`	Manually marked as resolved (not retried)
`retrying`	Retry in progress

POST /api/v1/events/dlq/:id/retry — Retry Single Event

POST https://api.septemcore.com/v1/events/dlq/dlq_01j9p000000001/retry
Authorization: Bearer <access_token>

Response 202 Accepted.

POST /api/v1/events/dlq/replay-all — Throttled Bulk Replay

Replays all pending DLQ events at a controlled rate:

POST https://api.septemcore.com/v1/events/dlq/replay-all
Authorization: Bearer <access_token>

Response 202 Accepted:

{
  "replayed":                 48,
  "skipped_already_resolved": 12
}

Parameter	Value
Replay rate	50 events/sec (`DLQ_REPLAY_RATE_LIMIT`)
Scope	Only `status=pending` — resolved events are skipped
Idempotency	Financial events use permanent `processed_event_ids` in PostgreSQL (not Valkey TTL — DLQ events may be older than 24 h)

Tenant Isolation

Layer	Mechanism
Publish	Gateway injects `tenantId` from JWT — module cannot substitute another tenant
Subscribe	SDK automatically filters by `tenantId` from JWT — cross-tenant event access is impossible
Kafka topics	Shared topics for all tenants; partition key = `entityId`. Topic-per-tenant would create millions of topics — one topic per domain is the industry standard

Broker Unavailability

Situation	Behaviour
Kafka down at `publish()`	Returns `503 Service Unavailable` (`problems/events.broker.unavailable`). Module decides: retry or ignore
Kafka down at `subscribe()`	SDK auto-reconnects. Consumer resumes from last committed offset on recovery
RabbitMQ down	Returns `503`. Transactional tasks wait for recovery

Error Reference

Error type	Status	Trigger
`problems/events.broker.unavailable`	`503`	Kafka or RabbitMQ is unreachable
`problems/events.publish.forbidden`	`403`	Module publishing an event not in `manifest.events.publishes[]`
`problems/events.subscribe.forbidden`	`403`	Module subscribing to topic not in `manifest.events.subscribes[]`
`problems/events.retention.exceeded`	`422`	Seek target timestamp is older than Kafka retention window
`problems/batch-limit-exceeded`	`400`	Batch publish exceeds 500 events
`problems/topic-not-found`	`404`	Topic does not exist
`problems/subscription-not-found`	`404`	Subscription ID does not exist

Event Bus REST API Reference

On this page