ntfy — Simple Push Notifications via HTTP PUT/POST

What ntfy Does

• HTTP Notifications: Send notifications with a single curl command
• Mobile Apps: Native Android and iOS apps with push notifications
• Web App: PWA for desktop notifications in the browser
• No Signup: Use ntfy.sh for free or self-host — no account needed
• Attachments: Send files and images with notifications
• Actions: Add clickable buttons and URLs to notifications
• Priority Levels: 5 priority levels from min to urgent (with different sounds)
• Scheduled Delivery: Schedule notifications for future delivery
• Authentication: Optional auth for private self-hosted instances
• UnifiedPush: Acts as UnifiedPush distributor for other apps

How It Works

Your Script                    ntfy Server              Your Phone
──────────                    ───────────              ──────────
curl -d "msg" ntfy.sh/topic ──▶ Store & Forward ──▶ Push notification
                                                       📱 *ding*

That's it. No OAuth, no webhooks to configure, no SDK to install.

Usage Examples

Basic Notification

# Simple message
curl -d "Deployment complete" ntfy.sh/my-alerts

# With title
curl -H "Title: Server Alert" -d "Disk usage above 90%" ntfy.sh/my-alerts

# With priority
curl -H "Priority: urgent" -H "Title: 🔴 DB Down" 
  -d "PostgreSQL is not responding" ntfy.sh/my-alerts

# With tags/emojis
curl -H "Tags: warning,rotating_light" 
  -d "CPU temperature 95°C" ntfy.sh/my-alerts

In Scripts

# Backup script
#!/bin/bash
if pg_dump mydb > backup.sql; then
  curl -d "✅ Database backup completed ($(du -h backup.sql | cut -f1))" ntfy.sh/backups
else
  curl -H "Priority: high" -H "Tags: x" 
    -d "❌ Database backup failed!" ntfy.sh/backups
fi

# Cron job monitoring
0 2 * * * /usr/local/bin/backup.sh && curl -d "Nightly backup OK" ntfy.sh/cron-alerts

# Long-running process
./train-model.py && curl -d "Model training complete! Accuracy: 94.2%" ntfy.sh/ml-alerts

With Actions (Clickable Buttons)

curl -H "Actions: view, Open Dashboard, https://grafana.example.com; 
  http, Restart Service, https://api.example.com/restart, method=POST" 
  -d "Service health check failed" ntfy.sh/my-alerts

With Attachments

# Send image
curl -T screenshot.png -H "Filename: error-screenshot.png" ntfy.sh/my-alerts

# Send with message and attachment URL
curl -H "Attach: https://example.com/report.pdf" 
  -d "Monthly report is ready" ntfy.sh/my-alerts

From Any Language

# Python
import requests
requests.post("https://ntfy.sh/my-alerts",
  data="Build #456 passed ✅",
  headers={"Title": "CI/CD", "Priority": "default"})

// JavaScript
fetch('https://ntfy.sh/my-alerts', {
  method: 'POST',
  body: 'Deployment to production complete',
  headers: { 'Title': 'Deploy', 'Priority': 'high' }
});

Self-Hosting

Docker

docker run -d --name ntfy 
  -p 80:80 
  -v ntfy-cache:/var/cache/ntfy 
  -v ntfy-etc:/etc/ntfy 
  binwiederhier/ntfy serve 
  --cache-file /var/cache/ntfy/cache.db

Docker Compose

services:
  ntfy:
    image: binwiederhier/ntfy
    command: serve
    ports:
      - "80:80"
    volumes:
      - ntfy-cache:/var/cache/ntfy
      - ./server.yml:/etc/ntfy/server.yml
    environment:
      TZ: Asia/Shanghai
    restart: unless-stopped

volumes:
  ntfy-cache:

Configuration

# server.yml
base-url: https://ntfy.yourdomain.com
cache-file: /var/cache/ntfy/cache.db
auth-file: /var/lib/ntfy/user.db
auth-default-access: deny-all  # Require auth
behind-proxy: true
attachment-cache-dir: /var/cache/ntfy/attachments

Authentication

# Add user
ntfy user add --role=admin admin
ntfy user add phil

# Grant access
ntfy access phil my-alerts rw    # read-write to "my-alerts"
ntfy access phil alerts ro       # read-only to "alerts"

# Use with auth
curl -u phil:password -d "Secret alert" ntfy.yourdomain.com/my-alerts

Priority Levels

ntfy vs Alternatives

常见问题

Q: ntfy.sh 公共服务安全吗？ A: ntfy.sh 的 topic 名称就是"密码"——任何知道 topic 名的人都能收到通知。对于敏感通知，建议使用长随机 topic 名或自托管并配置认证。

Q: 消息会被存储多久？ A: ntfy.sh 公共服务保存消息 12 小时。自托管可以通过 cache-duration 配置自定义保留时间。

Q: 可以用于生产环境的告警吗？ A: 可以。ntfy 支持与 Grafana、Prometheus Alertmanager、Uptime Kuma 等监控工具集成。通过 webhook 或直接 HTTP 调用即可发送告警通知到手机。

来源与致谢

• GitHub: binwiederhier/ntfy — 29.7K+ ⭐ | Apache-2.0
• 官网: ntfy.sh