Shoutrrr Notification Integration

Shoutrrr Notification Integration#

Zerobyte delegates all outbound notification delivery to the Shoutrrr CLI — a unified notification tool that speaks a common URL-based protocol for dozens of services. Rather than implementing per-service HTTP clients, Zerobyte converts its internal notification configs into Shoutrrr-scheme URLs and shells out to the shoutrrr binary at runtime.

The currently pinned version is v0.16.1 , sourced from the nicholas-fedor/shoutrrr fork. The binary is downloaded and placed at /usr/local/bin/shoutrrr during the Docker build for both amd64 and arm64 targets .

Supported Notification Types#

Nine notification types are defined in app/schemas/notifications.ts:

Type	Key fields
`email`	SMTP host/port, credentials, from/to, TLS
`slack`	Webhook URL, username, icon emoji
`discord`	Webhook URL, username, avatar URL, thread ID
`gotify`	Server URL, app token, path, priority (0–10)
`ntfy`	Server URL (optional), topic, priority, auth
`pushover`	User key, API token, devices, priority
`telegram`	Bot token, chat ID, thread ID
`generic`	Arbitrary HTTP webhook (GET/POST, headers, JSON)
`custom`	Raw Shoutrrr URL (pass-through)

All schemas are validated with Zod before a config is persisted or used.

URL Construction#

Each service type has a dedicated builder in app/server/modules/notifications/builders/ that translates a typed config object into a Shoutrrr protocol URL:

buildGotifyShoutrrrUrl — assembles gotify://<host>/<path>/<token>, sets DisableTLS=true for http:// URLs, appends priority as a query param
buildNtfyShoutrrrUrl — handles optional custom server, auth (username/password or access token), and priority enum
buildSlackShoutrrrUrl — parses the incoming webhook URL to extract token parts
buildDiscordShoutrrrUrl — extracts webhook ID and token; supports thread ID
buildEmailShoutrrrUrl — builds an SMTP URL with encoded credentials, TLS flag, and recipient list
buildPushoverShoutrrrUrl — encodes API token as the URL password and user key as the hostname
buildTelegramShoutrrrUrl — constructs telegram://<botToken>/chat?chatid=<chatId>
buildGenericShoutrrrUrl — supports arbitrary HTTP webhooks with method, content type, and custom headers
buildCustomShoutrrrUrl — returns the user-supplied URL unchanged

All builders are dispatched through a single entry point, buildShoutrrrUrl(config), which switches on config.type and throws on unhandled variants.

Delivery#

sendNotification in app/server/utils/shoutrrr.ts handles actual delivery:

Assembles CLI args: shoutrrr send --url <url> --title <title> --message <body>
Executes via safeExec
On non-zero exit, sanitizes the stderr/stdout via sanitizeSensitiveData before logging and returning an error — preventing credential leakage in logs

Backup Lifecycle Hooks#

sendBackupNotification() in notifications.service.ts is called by the backup lifecycle at four events: start, success, warning, and failure . For each assigned destination it:

Decrypts the stored config (credentials are encrypted at rest, )
Validates the target against WEBHOOK_ALLOWED_ORIGINS via assertNotificationTargetAllowed() to prevent SSRF
Calls buildShoutrrrUrl() → sendNotification()
Records the delivery result in the database

Credential & Security Notes#

Encryption at rest: All sensitive fields (tokens, passwords, webhook URLs) are encrypted before database storage and decrypted only at send time .
SSRF protection: The Gotify form UI reminds users that the server URL's origin must be listed in WEBHOOK_ALLOWED_ORIGINS . The same check applies to all outbound notification targets server-side.
Credential scrubbing: Error output from the shoutrrr CLI is passed through sanitizeSensitiveData before logging .
Token UI treatment: The Gotify app token field uses a SecretInput component (masked input) in the UI .

Key Source Files#

File	Purpose
`app/schemas/notifications.ts`	Zod schemas for all notification config types
`app/server/utils/shoutrrr.ts`	`sendNotification()` — shells out to Shoutrrr CLI
`app/server/modules/notifications/builders/index.ts`	`buildShoutrrrUrl()` dispatcher
`app/server/modules/notifications/builders/gotify.ts`	Gotify URL builder (reference implementation)
`app/server/modules/notifications/notifications.service.ts`	End-to-end pipeline: decrypt → validate → build → send
`Dockerfile`	Shoutrrr binary version pinning and installation