Post

Apprise: One Notification Interface for Your Homelab

Route script and service alerts to multiple destinations with Apprise configuration and tags.

Apprise: One Notification Interface for Your Homelab

A backup job, a monitoring check, and a deployment script may all need to send alerts, but each messaging service has its own API and credentials. Apprise gives those jobs a common notification interface. It can send through services including Discord, Telegram, email, and Gotify, using a command-line tool or Python library. An optional API server makes the same idea available over HTTP.

Apprise is an established project, not a new launch. Its practical appeal is that notification destinations can live in configuration while scripts use the same command. That reduces the service-specific code each script needs; it does not eliminate the need to protect credentials or verify delivery.

Start with a local configuration

The project documents installation with uv tool install apprise or pip install apprise. An isolated environment keeps Python dependencies separate from system packages. For example, with uv installed:

1
2
uv tool install apprise
apprise --version

Choose a destination from the supported services and follow its linked setup instructions. Each service has its own URL format and may require a webhook, token, or account configuration. Treat that URL as a password.

For a small setup, create a text file such as ~/.config/apprise.conf with one tagged destination per line. Replace the placeholders with actual service details; these examples are not working credentials:

1
2
ops=discord://WEBHOOK_ID/WEBHOOK_TOKEN
critical=gotify://YOUR_HOST/TOKEN

Restrict access to the file, for example with chmod 600 ~/.config/apprise.conf, and keep it out of Git and shared logs. File permissions do not protect it from other processes running as the same user. The configuration guide also documents YAML, multiple tags, and service-specific options.

Send a test to one group:

1
2
apprise --config "$HOME/.config/apprise.conf" --tag ops \
  --title 'Homelab test' --body 'Notification routing is working.'

Check the destination for the message and inspect the command’s exit status. A successful command is useful evidence that the service accepted the request, but it does not prove a person saw the alert. If it fails, check the service’s URL syntax, credentials, network access, and provider-side settings. Be careful with verbose logs: diagnostic output can contain sensitive configuration.

Route alerts by purpose

Tags let the same configuration serve different jobs. A routine backup could target ops, while a failed storage check targets critical. A destination can have multiple tags, so one channel can receive both without duplicating every script’s service URL.

Apprise documents repeated -g options as an OR: -g ops -g critical selects either tag. A comma within one option is an AND: -g ops,critical selects destinations with both. Check the CLI examples before building more complicated escalation rules, and test each route with a harmless message.

For a scheduled job, run the notification under the same user and environment as the job itself. An interactive shell may find a configuration file or executable that a scheduler cannot. Use explicit paths where needed, and arrange separate monitoring for the alert pipeline: a notification failure should not silently turn a failed backup into a successful one.

When an HTTP endpoint helps

The separate Apprise API provides an HTTP interface for software that cannot call the CLI or Python library directly. Its documented stateless endpoint accepts notification URLs in the request; stateful configuration can store destinations on the server. This adds another service to maintain and creates a place where credentials and notification content may be accessible.

Keep the endpoint on a trusted network, configure authentication appropriate to the deployment, and restrict access to stored configuration. Review the API project’s current deployment and access documentation before exposing it beyond a host. If a single local script is all you need, the CLI is a smaller starting point.

Apprise standardizes the sending side, while the chosen provider still controls delivery, account limits, formatting, and availability. Start with one destination and one test alert, then add routes only when you know who needs to receive them.

This post is licensed under CC BY 4.0 by the author.