Notification subscriptions (not released)

Shoehorn sends notifications for important events across the platform.

Notification Channels

Channel	Configuration	Use Case
In-App	Always enabled	All notifications
Email	SMTP configuration	Critical alerts, governance deadlines
Slack	Incoming webhook URL or bot token	Team channels, on-call alerts
Webhooks	URL + secret	External tool integration

Event Types

These are the events Shoehorn can notify on. A subscription routes one or more of these to a channel.

Event type	Description
`k8s.workload.unhealthy`	A workload is unhealthy
`k8s.workload.degraded`	A workload is running degraded
`k8s.workload.high_restarts`	A workload is restarting more than expected
`k8s.workload.oom_kill`	A container was killed for running out of memory
`k8s.workload.latest_tag`	A workload runs an image pinned to a mutable tag
`manifest.invalid`	An entity manifest failed validation
`forge.run.failed`	A Forge workflow run failed
`approval.pending`	A Forge run is waiting for your approval
`entity.license.expiring_soon`	An entity’s license is close to expiry
`entity.license.expired`	An entity’s license has expired
`governance.action.required`	A governance action needs your attention
`cloud.maintenance.scheduled`	A cloud provider scheduled maintenance
`cloud.maintenance.urgent`	A cloud provider announced urgent maintenance
`security.cve`	A CVE was found affecting an entity
`security.secret`	A leaked secret was detected
`scorecard.failed`	An entity failed a scorecard
`k8s.security.violation`	A Kubernetes security rule was violated
`subscription.auto_paused`	A subscription was paused after repeated delivery failures

Email Configuration

To enable email notifications, configure SMTP:

SMTP_ENABLED=true
SMTP_HOST=mail.smtp2go.com
SMTP_PORT=587
SMTP_USERNAME=shoehorn
SMTP_PASSWORD=your-password
SMTP_FROM=noreply@shoehorn.example.com

Until SMTP is configured, the email channel is hidden in the subscription wizard and the API rejects email subscriptions.

Slack Setup

A Slack channel runs in one of two modes. Pick the one that fits how your team works.

Webhook mode

Webhook mode posts to a single Slack channel through an Incoming Webhook URL.

Create a Slack app at api.slack.com/apps.
Open Incoming Webhooks and turn it on.
Add a new webhook and pick the channel it posts to.
Copy the webhook URL into the subscription.

Bot mode

Bot mode uses a bot token, so one app can post to any channel you choose.

Create a Slack app at api.slack.com/apps.
Under OAuth & Permissions, add the bot token scopes chat:write and chat:write.public. The second scope lets the bot post to channels it hasn’t joined.
Install the app to your workspace.
Copy the bot token. It starts with xoxb-.
Invite the bot to the target channel, then set the channel on the subscription.

Channel Secrets

A Slack or webhook channel needs a secret: a Slack webhook URL, a Slack bot token, or a webhook signing key. You can give it to Shoehorn two ways.

Save it in the portal. Paste the secret into the subscription. Shoehorn encrypts it before saving and never shows it again. After you save, the field just reads “secret is set”. This is the usual way.

Reference one from your Helm values. If the secret is already defined in your deployment’s Helm chart under notifications.secrets, point the subscription at it instead of pasting a value. Switch the field to “Reference an existing secret” and enter secret://<name>, using the name from your Helm values. The secret stays in your cluster and never reaches Shoehorn’s database.

Either way, Shoehorn never shows the secret value back in the UI.

Managing Notification subscriptions

Users can manage their notification preferences in Profile > Notification subscriptions.