Ntfy: Self-Hosted Push Notifications for Scripts, Servers, and CI/CD

Why Ntfy?

Getting alerts from servers shouldn’t require Slack, PagerDuty, or email. Ntfy makes it dead simple:

Zero configuration — curl -d "message" ntfy.sh/topic sends a push notification.
Phone + Desktop — Apps for Android, iOS, and web browser.
Self-hostable — Run your own instance for privacy and control.
Integrates with everything — Uptime Kuma, Grafana, cron, shell scripts, CI/CD.

Prerequisites

Docker (for self-hosted) or use the free public instance at ntfy.sh.
The Ntfy app on your phone (Android or iOS).

Step 1: Deploy with Docker (Self-Hosted)

docker run -d \
  --restart=always \
  -p 2586:80 \
  -v /var/cache/ntfy:/var/cache/ntfy \
  --name ntfy \
  binwiederhier/ntfy serve \
  --cache-file /var/cache/ntfy/cache.db

Access at http://your-server:2586.

Or just use the free public instance at https://ntfy.sh — no setup required.

Step 2: Send Notifications

Basic Message

curl -d "Deployment to production complete ✅" http://your-server:2586/deployments

With Title, Priority, and Tags

curl \
  -H "Title: Backup Failed" \
  -H "Priority: urgent" \
  -H "Tags: warning,backup" \
  -d "MySQL backup on db-server failed at $(date)" \
  http://your-server:2586/server-alerts

Priority Levels

Priority	Effect
`min`	No sound, no vibration
`low`	No sound
`default`	Normal notification
`high`	Overrides Do Not Disturb
`urgent`	Persistent, loud alert

Step 3: Common Use Cases

Cron Job Alerts

# /etc/crontab
0 2 * * * root /usr/local/bin/backup.sh && curl -d "✅ Backup done" ntfy.sh/my-server || curl -H "Priority: high" -d "❌ Backup FAILED" ntfy.sh/my-server

CI/CD Pipeline Notifications

# GitHub Actions / Gitea Actions
- name: Notify on success
  if: success()
  run: curl -d "Build ${{ github.sha }} passed ✅" ntfy.sh/ci-builds

- name: Notify on failure
  if: failure()
  run: curl -H "Priority: high" -d "Build ${{ github.sha }} FAILED ❌" ntfy.sh/ci-builds

# /etc/profile.d/ntfy-login.sh
curl -d "SSH login: $(whoami)@$(hostname) from ${SSH_CLIENT%% *}" ntfy.sh/ssh-logins

Troubleshooting

Problem	Solution
Notifications not arriving on phone	Ensure the app is subscribed to the exact topic name; check phone battery optimization settings
”Unauthorized” error	Enable authentication on self-hosted Ntfy; verify credentials
Messages delayed	Check if phone is in battery saver mode; verify server connectivity
Topic “hijacked” on public instance	Use a long random topic name or self-host for sensitive alerts

Summary

Send notifications with a single curl command.
Use priority levels to control urgency (from min to urgent).
Integrate with cron, CI/CD, Uptime Kuma, Grafana, and any HTTP-capable tool.
Self-host for control, or use the free ntfy.sh public instance.

Frequently Asked Questions

What is Ntfy and why use it?

Ntfy (pronounced 'notify') is an open-source push notification service you can self-host. It lets you send notifications to your phone or desktop from scripts, cron jobs, CI/CD pipelines, or any system that can make an HTTP request. No app registration, no API keys — just POST a message to a topic URL.

How do I send a notification from a shell script?

Run: curl -d 'Backup completed successfully' ntfy.sh/my-alerts. That's it. You can also set a title, priority, and tags using HTTP headers.

Is Ntfy secure? Can anyone read my notifications?

If you self-host Ntfy, you control access completely. You can enable authentication to require username/password for publishing and subscribing. The public ntfy.sh instance has no authentication, so anyone who knows your topic name can subscribe — use random topic names or self-host for sensitive alerts.

Can I integrate Ntfy with monitoring tools like Uptime Kuma or Grafana?

Yes. Uptime Kuma, Grafana, Prometheus Alertmanager, and many other tools support Ntfy as a notification target. In most cases, you just enter the Ntfy topic URL in the webhook/notification settings.