Notifications Overview
Audience: operators evaluating or rolling out Notify, on-call leads tuning alert rules, and engineers integrating the notifications engine.
Notifications Studio turns raw platform events into concise, tenant-scoped alerts that reach the right responders without overwhelming them. It is the alerting surface of the Stella Ops release control plane: the service is sovereign and offline-first, follows the Aggregation-Only Contract (AOC), and produces deterministic outputs so the same configuration yields identical deliveries across environments.
For the full module reference, start with the Notify module README.
1. Mission & value
- Reduce noise. Only materially new or high-impact changes reach chat, email, or webhooks thanks to rule filters, throttles, and digest windows.
- Explainable results. Every delivery is traceable back to a rule, action, and event payload stored in the delivery ledger; operators can audit what fired and why.
- Safe by default. Secrets remain in external stores, templates are sandboxed, quiet hours and throttles prevent storms, and idempotency guarantees protect downstream systems.
- Offline-aligned. All configuration, templates, and plug-ins ship with Offline Kits; no external SaaS is required to send notifications.
2. Core capabilities
| Capability | What it does | Key docs |
|---|---|---|
| Rules engine | Declarative matchers for event kinds, severities, namespaces, VEX context, KEV flags, and more. | rules.md |
| Channel catalog | Slack, Teams, Email, Webhook connectors loaded via restart-time plug-ins; metadata stored without secrets. | architecture.md |
| Templates | Locale-aware, deterministic rendering via safe helpers; channel defaults plus tenant-specific overrides, including the attestation lifecycle suite (tmpl-attest-*). | templates.md |
| Digests | Coalesce bursts into periodic summaries with deterministic IDs and audit trails. | digests.md |
| Delivery ledger | Tracks rendered payload hashes, attempts, throttles, and outcomes for every action. | architecture.md |
| Ack tokens | DSSE-signed acknowledgement tokens with webhook allowlists and escalation guardrails enforced by Authority. | architecture.md |
3. How it fits into Stella Ops
- Producers emit events. Scanner, Scheduler, VEX Lens, Attestor, and Zastava publish canonical envelopes (
NotifyEvent) onto the internal bus. - Notify.Worker evaluates rules. For each tenant, the worker applies match filters, VEX gates, throttles, and digest policies before rendering the action.
- Connectors deliver. Channel plug-ins send the rendered payload to Slack/Teams/Email/Webhook targets and report back attempts and outcomes.
- Consumers investigate. Operators pivot from message links into Console dashboards, SBOM views, or policy overlays with correlation IDs preserved.
The Notify WebService fronts worker state with REST APIs used by the UI and CLI. Tenants authenticate via StellaOps Authority scopes notify.viewer, notify.operator, and (for escalated actions) notify.admin. Tenant isolation is resolved from the validated stellaops:tenant claim; a gateway-forwarded X-StellaOps-TenantId header is envelope context, not a second required tenancy source.
4. Operating model
| Area | Guidance |
|---|---|
| Tenancy | Each rule, channel, template, and delivery belongs to exactly one tenant. Cross-tenant sharing is intentionally unsupported. |
| Determinism | Configuration persistence normalises strings and sorts collections. Template rendering produces identical bodyHash values when inputs match; attestation events always reference the canonical tmpl-attest-* keys documented in the template guide. |
| Scaling | Workers scale horizontally; per-tenant rule snapshots are cached and refreshed from PostgreSQL change notifications. Valkey (or Redis-compatible) guards throttles and locks. |
| Offline | Offline Kits include plug-ins, default templates, and seed rules. Operators can edit YAML/JSON manifests before air-gapped deployment. |
| Security | Channel secrets use indirection (secretRef), Authority-protected OAuth clients secure API access, and delivery payloads are redacted before storage where required. |
| Module boundaries | 2025-11-02 decision: keep src/Notify/ as the shared notification toolkit and src/Notifier/ as the Notifications Studio runtime host until a packaging RFC covers the implications of merging. |
5. Getting started (first 30 minutes)
| Step | Goal | Reference |
|---|---|---|
| 1 | Deploy Notify WebService + Worker with PostgreSQL and Valkey | architecture.md |
| 2 | Register OAuth clients/scopes in Authority | etc/authority.yaml.sample (repo root) |
| 3 | Install channel plug-ins and capture secret references | plugins/notify (repo root) |
| 4 | Create a tenant rule and test preview | POST /channels/{id}/test |
| 5 | Inspect deliveries and digests | /api/v1/notify/deliveries, /api/v1/notify/digests |
6. Where to go next
| Goal | Reference |
|---|---|
| Deep-dive on runtime shape, data model, and APIs | architecture.md |
| Author and tune rules | rules.md |
| Write deterministic templates | templates.md |
| Configure digests and quiet hours | digests.md |
| Operate the service (quotas, retries, observability) | operations/quotas.md, operations/retries.md, operations/observability.md |