Event Taxonomy (Canonical)¶
Purpose¶
Define domain events for async workflows with stable names, payload contracts, ownership, and idempotency behavior.
Naming Convention¶
<domain>.<entity_or_process>.<action>
Examples:
- provisioning.requested
- billing.balance_depleted
Envelope Contract¶
All events follow envelope:
- event_id (uuid)
- event_type (string)
- occurred_at (RFC3339 UTC)
- version (semver-like string)
- correlation_id (trace/correlation id)
- payload (typed object)
Event Catalog¶
| Event | Producer | Consumers | Idempotency Key | Notes |
|---|---|---|---|---|
| provisioning.requested | Orchestrator | Provisioning Worker | allocation_id | starts provisioning workflow |
| provisioning.active | Provisioning Worker | Billing, Notification Relay | allocation_id + started_at | allocation usable |
| provisioning.failed | Provisioning Worker | API read model, Notification Relay | allocation_id + reason hash | terminal failure state |
| provisioning.force_release_requested | Billing Worker | Provisioning Worker | user_id + window | release due to policy (balance depleted) |
| provisioning.releasing.requested | Provisioning Orchestrator | Provisioning Worker | allocation_id | user/system-initiated release started |
| provisioning.releasing.completed | Provisioning Worker | Billing, Notification Relay | allocation_id + released_at | node unassigned, usage window closed |
| provisioning.release_failed | Provisioning Worker | Billing, Notification Relay | allocation_id + failed_at | all retries exhausted; billing stops, admin intervention required |
| billing.low_balance_warning | Billing Worker | Notification Relay | user_id + threshold_window | one-time per low-state transition |
| billing.auto_release_pending | Billing Worker | Notification Relay | user_id + projected_depletion_at | warning that forced release is approaching based on projected depletion |
| billing.balance_depleted | Billing Worker | Notification Relay, Provisioning | user_id + depleted_at | triggers force release |
| payments.balance_credited | Payments Service | Billing Read Model | stripe_event_id | credit applied after idempotent webhook post |
| payments.reconcile_failed | Payments Service | Notification Relay, Ops | stripe_event_id + payment_session_id | mismatch or provider failure requiring support follow-up |
Versioning Rules¶
- Additive payload fields -> minor event version.
- Breaking payload changes -> new event version and dual-consume window.
Retry/DLQ Rules¶
- Consumers must be idempotent.
- Retry with exponential backoff.
- Poison events routed to DLQ with replay tooling.