Event Subscription Model
Summary
The Event Subscription Model defines how external services register interest in Keymate platform events and receive notifications when those events occur. Subscribers create subscriptions that specify which events to receive, where to deliver them, and how to authenticate the delivery request. The model supports multiple callback protocols and authentication methods to integrate with diverse downstream systems.
Why It Exists
Event-driven architectures require a contract between event producers and consumers. Without a formal subscription model:
- Services cannot selectively receive only the events they need
- Event delivery lacks authentication, creating security gaps
- Protocol mismatches prevent integration with legacy systems
- There is no way to pause or manage event flow per subscriber
The subscription model provides a declarative way for services to register their event interests with authentication and delivery preferences.
Where It Fits in Keymate
The subscription model operates within the Integration Hub, connecting the event bus to external consumers.
When a platform component publishes an event, the Subscription Manager identifies matching subscriptions and delivers the event payload to each subscriber's endpoint using the configured protocol and authentication.
Boundaries
What it covers:
- Event type definitions and registration
- Subscription lifecycle (create, update, delete, list)
- Callback protocol selection
- Subscriber authentication configuration
- Delivery endpoint management
What it does not cover:
- Event payload schema design (handled by event producers)
- Retry and dead-letter queue handling (see Outbox and DLQ Handling)
- Event bus infrastructure setup (see Event Bus Integration)
How It Works
Event Definition
Events represent significant occurrences in the platform that external systems may need to react to. Each event definition includes:
| Field | Description |
|---|---|
| id | Unique identifier (UUID) |
| source_service | Service that produces the event |
| resource_type | Type of resource affected (user, policy, organization) |
| operation_type | Operation performed (created, updated, deleted) |
| event_type | Optional classification label |
Events follow a composite key pattern: source_service + resource_type + operation_type uniquely identifies an event type.
Subscription Structure
A subscription binds a subscriber to one or more event types and specifies delivery details:
| Field | Description |
|---|---|
| id | Unique subscription identifier (UUID) |
| event_id | Reference to the event definition |
| subscriber_service | Name of the subscribing service |
| delivery_endpoint | URL where events are delivered |
| callback_protocol | Protocol for delivery (gRPC, HTTP, SOAP, WebSocket) |
| request_method | HTTP method for HTTP callbacks |
| active | Whether the subscription is enabled |
| auth | Authentication configuration for delivery |
| payload_type | Expected payload format |
Callback Protocols
The subscription model supports multiple delivery protocols:
| Protocol | Use Case |
|---|---|
| HTTP | Standard webhook delivery via HTTP POST |
| gRPC | High-performance delivery for internal services |
| SOAP | Integration with legacy enterprise systems |
| WebSocket | Real-time streaming to connected clients |
Authentication Types
Subscribers configure authentication to secure event delivery. The Subscription Manager includes credentials when calling the subscriber's endpoint:
| Auth Type | Fields | Description |
|---|---|---|
| BASIC | username, password | HTTP Basic authentication header |
| OAUTH2 | client_id, client_secret, token_url, scope | OAuth 2.0 client credentials flow |
| JWT | token | Pre-shared JWT bearer token |
| APIKEY | key, header_name | API key in a custom header |
All subscriptions must include authentication configuration. Subscriptions without authentication are rejected to prevent unauthorized event delivery.
Subscription Lifecycle
Subscriptions can be paused by setting active: false without deleting the configuration. This allows temporary suspension of event delivery during maintenance or incident response.
Diagram
Example Scenario
Scenario
An analytics service needs to receive notifications when the platform creates users, to update usage dashboards.
Input
- Actor: Analytics service administrator
- Resource: User creation events
- Action: Create subscription for
user.createdevent type - Context: HTTP callback with API key authentication
Expected Outcome
- Subscription Manager creates a new subscription record
- When the platform creates a user, the Subscription Manager delivers the event to
https://analytics.example.com/events - Delivery includes the configured API key in the
X-API-KEYheader - Analytics service processes the event and updates dashboards
Common Misunderstandings
- Subscriptions filter event content — Subscriptions select which event types to receive, but do not filter fields within the event payload. All subscribers receive the full event payload.
- Pausing a subscription drops events — When a subscription is paused, events are not delivered but may be retried when the subscription is reactivated (depending on retention policy).
The system stores subscription authentication credentials securely but transmits them to the subscriber's endpoint during delivery. Ensure delivery endpoints use TLS to protect credentials in transit.
Design Notes / Best Practices
- Use descriptive
subscriber_servicenames to identify subscriptions in logs and dashboards - Prefer OAUTH2 or JWT authentication over BASIC for production integrations
- Test subscriptions with a low-traffic event type before subscribing to high-volume events
- Monitor delivery success rates and configure alerts for persistent failures
Use the active flag to temporarily pause subscriptions during subscriber maintenance without losing the subscription configuration.
Related Use Cases
- Audit log synchronization to external SIEM systems
- Real-time user provisioning to downstream applications
- Policy change notifications to API gateways
- Organization hierarchy updates to analytics platforms