Self-hosted push notifications with ntfy — publishing, authentication, priorities, and integration patterns for scripts and monitoring
ntfy (pronounce "notify") is a self-hosted push notification service. Send notifications from scripts, cron jobs, and monitoring systems to your phone.
curl -d "Backup completed successfully" https://ntfy.example.com/my-topic
curl -H "Title: Backup Status" \
-H "Priority: high" \
-H "Tags: white_check_mark,backup" \
-d "Daily backup completed in 5 minutes" \
https://ntfy.example.com/backups
# Token auth (preferred)
curl -H "Authorization: Bearer YOUR_TOKEN" \
-d "Message here" \
https://ntfy.example.com/topic
# Basic auth
curl -u username:password \
-d "Message here" \
https://ntfy.example.com/topic
curl -H "Click: https://grafana.example.com/d/alerts" \
-H "Title: Disk Alert" \
-H "Priority: urgent" \
-H "Tags: warning" \
-d "Disk usage above 90% on /dev/sda1" \
https://ntfy.example.com/alerts
curl -H "Actions: view, Open Grafana, https://grafana.example.com; http, Restart Service, https://api.example.com/restart, method=POST" \
-d "Service is down" \
https://ntfy.example.com/alerts
curl -T /var/log/backup.log \
-H "Filename: backup.log" \
-H "Title: Backup Log" \
https://ntfy.example.com/backups
| Priority | Keyword | Value | Use for |
|---|---|---|---|
| Max | max / urgent | 5 | Service down, security alerts |
| High | high | 4 | Backup failures, disk warnings |
| Default | default | 3 | Routine notifications |
| Low | low | 2 | Info, non-urgent updates |
| Min | min | 1 | Debug, verbose logging |
Common tags for notifications:
| Tag | Emoji | Use for |
|---|---|---|
white_check_mark | ✅ | Success |
x | ❌ | Failure |
warning | ⚠️ | Warning |
rotating_light | 🚨 | Critical alert |
floppy_disk | 💾 | Backup |
whale | 🐳 | Docker |
movie_camera | 🎥 | Media/Plex |
gear | ⚙️ | System/config |
chart_with_upwards_trend | 📈 | Monitoring |
Full list: https://docs.ntfy.sh/emojis/