Skip to content
SHC Docs

Notification module

Layer 5. Objects. Objects

Webhook-based notifications for system events.

  • Pattern matching on event codes
  • Rate limiting (debounce and cooldown)
  • Jinja2 templating
config.yaml
notifications:
- name: slack-critical
url: https://hooks.slack.com/...
patterns:
- "V500*" # All 500-level events
- "A*" # All audit events
cooldown: 300

A cluster ships four rules, for the backup failure codes and a late schedule, so a failed, skipped or cancelled backup, or a schedule the dispatcher stopped firing, reaches someone without a rule written by hand. They send through one provider, notification.providers.operator, which the operator defines once:

Terminal window
shc config set notification.providers.operator.type webhook
shc config set notification.providers.operator.url https://hooks.example.com/shc
RuleCodesDebounceCooldown
backup-failedX500473BKPNOA, X500474BKPSRQ, X500467BKPHKF, X507831BKSCSP5mnone
backup-fire-droppedX500204BKSCSK, X500205BKSCTO5m1h
backup-unprotectedX500470BKPCOV, X500478BKPPRO, X200091BKPCOWnone24h
schedule-lateX500617SCHLAT5m24h

Until the provider is defined, shc notification ls lists each shipped rule with channel none and destination nowhere to send: notification.providers.operator is not defined. Such a rule is never sent and stops nothing from starting, and shc doctor warns about it without failing the run. A rule in notifications with one of these names replaces the shipped rule of that name.

Glob-style patterns on event/error class codes:

PatternMatches
V500*All V-prefixed 500-level events
A*All audit events
H*All health events
X400*All 400-level errors
*Everything
SettingDescription
debounceWait N after the first event, then send every event held since as one notification. A steady stream is sent once every N
cooldownAfter sending, ignore the same event class for N

Duration format: 30s, 5m, 1h, 1d.

SettingDefaultDescription
retries3Max retry attempts on failure
timeout10sHTTP request timeout

Retry sequence: 1s → 2s → 4s (exponential backoff, ×2 multiplier).

Templates use native Jinja2 syntax ({{ var }}, {% if %}, etc.). The notification engine passes template strings straight to Jinja2 with no pre-processing:

VariableDescription
{{ event.code }}Event class name (e.g., V500100)
{{ event.message }}Rendered event message
{{ event.payload }}Original event kwargs
{{ context.tenant }}Tenant name
{{ context.stack }}Stack name (may be null)
{{ context.environment }}Environment name (may be null)
{{ timestamp }}ISO 8601 UTC timestamp

Standard Jinja2 filters available: default, to_json, to_yaml, upper, lower, quote, basename.

Default templates ship for Slack, Discord, Teams, Telegram, PagerDuty, GoAlert, Pushover, and ntfy; everything else uses the generic JSON body.

# config.yaml (any scope)
notifications:
- name: slack-critical
url: !ref+vault://notifications/slack-webhook
on:
- "V500*"
- "X500*"
- "H500*"
debounce: "30s"
cooldown: "5m"
retries: 3
timeout: "10s"
body: |
text: "{{ event.message }}"
blocks:
- type: section
text:
type: mrkdwn
text: |
*Event:* `{{ event.code }}`
*Tenant:* {{ context.tenant }}
*Stack:* {{ context.stack | default('N/A') }}
*Time:* {{ timestamp }}

All providers use HTTP webhooks - no external packages required.

ProviderURL PatternAuto-Detection
Slackhooks.slack.com✅
Discorddiscord.com/api/webhooks✅
Microsoft Teamswebhook.office.com✅
Telegramapi.telegram.org✅
PagerDutyevents.pagerduty.com✅
GoAlert/api/v2/generic/incoming (path, any host)✅
Pushoverapi.pushover.net✅
ntfyntfy in URL✅
Email (SMTP)N/A (use email: config)N/A
GenericAny other URLDefault

GoAlert is the one path-detected flavor: a self-hosted pager has no fixed host. The integration key rides in the URL (?token=), so the whole configuration is the URL an operator pastes from GoAlert’s service page. Day-two setup is in Paging.

notifications:
- name: email-critical
url: "" # Not used for email
on: ["V500*"]
email:
host: smtp.example.com
port: 587
tls: true
password: ref+vault://smtp_password
to:
subject: "[SHC] {{ event.code }}: {{ event.message }}"