Documentation
Notifiers
ntfy Notifications for Server Updates - Push Notifications via ntfy.sh

ntfy Notifications for Server Updates - Push Notifications via ntfy.sh

Update-Watcher sends push notifications through ntfy, an open-source push notification service. ntfy uses a simple topic-based pub/sub model – you publish to a topic, and any device subscribed to that topic receives the notification instantly. You can use the free public server at ntfy.sh or host your own ntfy instance for full control over your notification infrastructure.

Setup for ntfy

Step 1: Choose a Topic Name

Choose a unique topic name. Topics are public by default on ntfy.sh, so use something unguessable (e.g., update-watcher-a7f3b2c1 rather than updates).

Step 2: Subscribe on Your Devices

Subscribe to the topic on your phone by installing the ntfy app (available on F-Droid and Google Play) and adding your topic.

Step 3: Optional Web Subscription

Optionally, subscribe in a web browser at https://ntfy.sh/your-topic-name.

No account or API key is required for the public server. However, if you want access control, you can create a free account on ntfy.sh and use token-based authentication.

config.yaml
notifiers:
  - type: ntfy
    topic: "update-watcher-a7f3b2c1"
    priority: "default"

Step 1: Deploy ntfy

Deploy ntfy following the self-hosting guide.

Step 2: Configure Authentication

Create a user and access token if you have authentication enabled.

Step 3: Choose a Topic

Choose a topic name for your Update-Watcher notifications.

Step 4: Subscribe on Devices

Subscribe on your devices using your server URL and topic.

Store the access token in an environment variable rather than placing it directly in your configuration file.
Terminal
export UPDATE_WATCHER_NTFY_TOKEN="<your-ntfy-access-token>"
config.yaml
notifiers:
  - type: ntfy
    topic: "server-updates"
    server_url: "https://ntfy.example.com"
    token: ${UPDATE_WATCHER_NTFY_TOKEN}
    priority: "high"

Configuration Options

OptionRequiredDefaultDescription
topicYes–The ntfy topic name to publish to. Choose something unique and unguessable for public servers.
server_urlNohttps://ntfy.shBase URL of the ntfy server. Change this if you are self-hosting ntfy.
tokenNo–Access token for authenticated ntfy servers. Not required for the public ntfy.sh server without access control. Use an environment variable reference.
priorityNo–Notification priority level. Values: min, low, default, high, urgent. When security updates are detected, the priority may be automatically elevated.

Configuration Example

Public ntfy.sh Server

config.yaml
notifiers:
  - type: ntfy
    topic: "update-watcher-a7f3b2c1"
    priority: "default"

Self-Hosted ntfy with Authentication

config.yaml
notifiers:
  - type: ntfy
    topic: "server-updates"
    server_url: "https://ntfy.example.com"
    token: ${UPDATE_WATCHER_NTFY_TOKEN}
    priority: "high"

Minimal Configuration

config.yaml
notifiers:
  - type: ntfy
    topic: "update-watcher-a7f3b2c1"

Notification Format

ntfy notifications include:

  • Title – Server hostname and update count.
  • Body – A text summary listing each checker and its available updates, with package names and versions.
  • Priority – Maps to ntfy’s priority system, which controls notification sound and display behavior on mobile devices.
  • Tags – Update-Watcher sets appropriate tags that ntfy renders as emoji indicators in the notification.

On mobile, ntfy notifications appear as standard push notifications with the configured priority level controlling the alert sound and vibration pattern.

Topic Security

On the public ntfy.sh server, anyone who knows a topic name can subscribe to it. To protect your update notifications:

  • Use a long, random topic name – Treat the topic name like a password. A UUID or random string is ideal.
  • Self-host ntfy – Run your own server and configure authentication for full access control.
  • Use access tokens – On ntfy.sh or self-hosted instances with access control enabled, use token-based authentication to restrict who can publish and subscribe.

Testing

Run Update-Watcher to verify the ntfy notification:

Terminal
update-watcher run

Check the ntfy app on your phone or the web interface for the notification. If no updates are available and send_policy is only-on-updates, temporarily set send_policy: "always" to force a notification.

For troubleshooting:

Terminal
update-watcher run --verbose

A successful delivery returns HTTP status 200 OK from the ntfy server. If you receive a 401 Unauthorized, verify your access token. If using a self-hosted server, ensure it is reachable from the machine running Update-Watcher.

💡
Testing tip: If no updates are available on your system, temporarily set send_policy: "always" in your configuration to force a notification and verify the integration is working.

Related

Receive update notifications for APT, Docker, WordPress, and 11 more checkers.

Email Notifications for Server Updates - SMTP / HTML Email AlertsPushover Notifications for Server Updates - iOS, Android & Desktop Alerts