9f6e6f7fb3
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Signals CI & Image / signals-ci (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
52 lines
2.7 KiB
Markdown
52 lines
2.7 KiB
Markdown
# Notification Channels
|
||
|
||
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||
|
||
Last updated: 2025-11-25 (Docs Tasks Md.V · DOCS-NOTIFY-40-001)
|
||
|
||
## Supported channel types
|
||
- **Slack / Teams**: webhook-based with optional slash-command ack URLs.
|
||
- **Email (SMTP/SMTPS)**: relay-only; secrets provided via `secretRef` in Authority.
|
||
- **Generic webhook**: signed (HMAC-SHA256) payloads with replay protection and allowlisted hosts.
|
||
- **Pager duty-style escalation webhooks**: same contract as generic webhooks but with escalation metadata.
|
||
- **Console in-app**: stored delivery rendered in UI; always enabled for each tenant.
|
||
|
||
## Channel resource schema (Notify API)
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"tenant": "string",
|
||
"type": "slack|teams|email|webhook|pager|console",
|
||
"endpoint": "https://..." ,
|
||
"secretRef": "authority://secrets/notify/slack-hook", // optional per type
|
||
"labels": { "env": "prod", "team": "sre" },
|
||
"throttle": { "windowSeconds": 60, "max": 10 },
|
||
"quietHours": { "from": "22:00", "to": "06:00", "timezone": "UTC" },
|
||
"enabled": true,
|
||
"createdUtc": "2025-11-25T00:00:00Z"
|
||
}
|
||
```
|
||
- **Determinism**: channel ids are UUIDv5 seeded by `(tenant, type, endpoint)` when created via manifests; server generates new IDs for ad-hoc API calls.
|
||
- **Validation**: endpoints must be on the allowlist; secretRef must exist in Authority; quiet hours use 24h clock UTC.
|
||
|
||
## Connector rules
|
||
- No secrets are stored in Notify DB; only `secretRef` is persisted.
|
||
- Per-tenant allowlists control outbound hostnames/ports; defaults block public internet in air-gapped kits.
|
||
- Payload signing:
|
||
- Slack/Teams: bearer secret in URL (indirect via secretRef) plus optional HMAC header `X-Stella-Signature` for mirror validation.
|
||
- Webhook/Pager: HMAC `X-Stella-Signature` (hex) over body with nonce + timestamp; receivers must enforce 5‑minute skew.
|
||
|
||
## Offline posture
|
||
- Offline kits ship default channel manifests under `out/offline/notify/channels/*.json` with placeholder endpoints.
|
||
- Operators must replace endpoints and secretRefs before deploy; validation rejects placeholder values.
|
||
|
||
## Observability
|
||
- Emit `notify.channel.delivery` counter with tags: `channel_type`, `tenant`, `status` (success/fail/throttled/quiet_hours), `rule_id`.
|
||
- Store delivery attempt hashes in the delivery ledger; duplicate payloads are de-duplicated per `(channel, bodyHash)` for 24h.
|
||
|
||
## Safety checklist
|
||
- [ ] Endpoint on allowlist and TLS valid.
|
||
- [ ] `secretRef` exists in Authority and scoped to tenant.
|
||
- [ ] Quiet hours configured for non-critical alerts; throttles set for bursty rules.
|
||
- [ ] HMAC signing verified in downstream system (webhook/pager).
|