homelab-optimized/docs/services/admin/ntfy-quick-reference.md

📱 NTFY Quick Reference

Quick reference guide for NTFY notification system usage

Basic Usage

Send Simple Message

curl -d "Hello World" https://ntfy.vish.gg/topic-name

Send with Authentication

curl -u username:password -d "Authenticated message" https://ntfy.vish.gg/topic-name

Send with Title

curl -H "Title: Alert Title" -d "Message body" https://ntfy.vish.gg/topic-name

Priority Levels

Set Message Priority

# Low priority (1-2)
curl -H "Priority: 1" -d "Debug message" https://ntfy.vish.gg/topic-name

# Normal priority (3) - default
curl -d "Normal message" https://ntfy.vish.gg/topic-name

# High priority (4-5)
curl -H "Priority: 5" -d "CRITICAL ALERT" https://ntfy.vish.gg/topic-name

Priority Reference

• 1 (Min): 🔕 Silent, debugging
• 2 (Low): 🔔 Quiet notification
• 3 (Default): 🔔 Normal notification
• 4 (High): 📢 Important, loud
• 5 (Max): 🚨 Critical, emergency

Tags and Emojis

Common Tags

# Success notifications
curl -H "Tags: white_check_mark,success" -d "Backup completed" https://ntfy.vish.gg/backups

# Warning notifications
curl -H "Tags: warning,yellow_circle" -d "High CPU usage" https://ntfy.vish.gg/alerts

# Error notifications
curl -H "Tags: x,red_circle" -d "Service failed" https://ntfy.vish.gg/alerts

# Info notifications
curl -H "Tags: information_source,blue_circle" -d "System update" https://ntfy.vish.gg/info

Popular Emoji Tags

• ✅ Success: white_check_mark, heavy_check_mark
• ⚠️ Warning: warning, yellow_circle
• ❌ Error: x, red_circle, no_entry
• 🔥 Critical: fire, rotating_light
• 📊 Monitoring: bar_chart, chart_with_upwards_trend
• 🔧 Maintenance: wrench, hammer_and_wrench
• 💾 Backup: floppy_disk, package

Actions and Buttons

Add Action Buttons

curl -H "Actions: view, Open Dashboard, https://grafana.local" \
     -d "Check system metrics" \
     https://ntfy.vish.gg/monitoring

Multiple Actions

curl -H "Actions: view, Dashboard, https://grafana.local; http, Restart, https://portainer.local/restart" \
     -d "Service needs attention" \
     https://ntfy.vish.gg/alerts

Common Homelab Topics

System Topics

• homelab-alerts - Critical system alerts
• homelab-monitoring - Monitoring notifications
• homelab-backups - Backup status
• homelab-updates - System updates
• homelab-security - Security alerts

Service Topics

• plex-alerts - Plex Media Server
• arr-suite - Sonarr/Radarr/Lidarr
• gitea-notifications - Git events
• portainer-alerts - Container alerts

Authentication

User Credentials

# Set credentials for session
export NTFY_USER="monitoring"
export NTFY_PASS="REDACTED_PASSWORD"

# Use in curl commands
curl -u "$NTFY_USER:$NTFY_PASS" -d "Message" https://ntfy.vish.gg/topic

Topic Permissions

• Read (r): Subscribe and receive messages
• Write (w): Publish messages to topic
• Read-Write (rw): Full access to topic

Scheduling and Delays

Delayed Messages

# Send in 30 minutes
curl -H "At: $(date -d '+30 minutes' '+%Y-%m-%dT%H:%M:%S')" \
     -d "Scheduled maintenance reminder" \
     https://ntfy.vish.gg/maintenance

Recurring Reminders

# Daily backup reminder (use with cron)
0 9 * * * curl -d "Daily backup check" https://ntfy.vish.gg/reminders

Monitoring Integration Examples

Prometheus AlertManager

# In alertmanager webhook
curl -u alerts:password \
     -H "Title: {{ .GroupLabels.alertname }}" \
     -H "Priority: 4" \
     -H "Tags: fire,prometheus" \
     -d "{{ range .Alerts }}{{ .Annotations.summary }}{{ end }}" \
     https://ntfy.vish.gg/REDACTED_NTFY_TOPIC

Uptime Kuma

# Service down notification
curl -u monitoring:password \
     -H "Title: Service Down: Plex" \
     -H "Priority: 5" \
     -H "Tags: rotating_light,down" \
     -d "Plex Media Server is not responding" \
     https://ntfy.vish.gg/homelab-monitoring

Backup Scripts

#!/bin/bash
# backup-notify.sh
if [ "$1" = "success" ]; then
    curl -u backup:password \
         -H "Title: Backup Completed" \
         -H "Tags: white_check_mark,backup" \
         -d "Daily backup completed successfully at $(date)" \
         https://ntfy.vish.gg/homelab-backups
else
    curl -u backup:password \
         -H "Title: Backup Failed" \
         -H "Priority: 4" \
         -H "Tags: x,backup,warning" \
         -d "Daily backup failed: $2" \
         https://ntfy.vish.gg/homelab-backups
fi

Client Subscription

Command Line

# Subscribe to topic
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC

# Subscribe with authentication
ntfy subscribe --user monitoring:password https://ntfy.vish.gg/REDACTED_NTFY_TOPIC

# Subscribe to multiple topics
ntfy subscribe https://ntfy.vish.gg/REDACTED_NTFY_TOPIC,homelab-backups

Mobile Apps

1. Install NTFY app (Android/iOS)
2. Add server: https://ntfy.vish.gg
3. Subscribe to topics: Enter topic names
4. Set credentials: Username/password if required

Troubleshooting

Test Connectivity

# Basic connectivity test
curl -I https://ntfy.vish.gg

# Test topic publishing
curl -d "Test message" https://ntfy.vish.gg/test

# Test authentication
curl -u username:password -d "Auth test" https://ntfy.vish.gg/test

Debug Message Delivery

# Check message history
curl -s https://ntfy.vish.gg/topic-name/json

# Monitor real-time messages
curl -N -H "Accept: text/event-stream" https://ntfy.vish.gg/topic-name/sse

Common Error Codes

• 401 Unauthorized: Invalid credentials
• 403 Forbidden: No permission for topic
• 404 Not Found: Topic doesn't exist
• 429 Too Many Requests: Rate limit exceeded

Best Practices

Topic Naming

• Use kebab-case: homelab-alerts
• Be descriptive: plex-transcoding-alerts
• Group by service: arr-suite-downloads
• Include environment: prod-database-alerts

Message Content

• Clear titles: Describe the issue/event
• Actionable messages: Include next steps
• Consistent formatting: Use templates
• Appropriate priority: Don't overuse high priority

Security

• Unique credentials: Different users for different services
• Minimal permissions: Grant only necessary access
• Regular rotation: Change passwords periodically
• Monitor usage: Track message patterns

---

Quick Access: https://ntfy.vish.gg | Admin: monitoring:password | Critical: homelab-alerts