# 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).