notifier/docs/NTFY_GUIDE.md

Ntfy Integration Guide

This guide explains how to use ntfy.sh notifications with the Notifier service.

What is Ntfy?

ntfy is a simple HTTP-based pub-sub notification service. You can send notifications to your phone, desktop, or any device that subscribes to your topics. It's perfect for:

• Push notifications to mobile devices
• Desktop notifications
• Server alerts and monitoring
• CI/CD pipeline notifications
• IoT device notifications

Authentication Methods

1. Token-Based Authentication (Recommended)

Token authentication is the preferred method for ntfy.sh.

Access Tokens (for authenticated topics)

notifiers:
  ntfy:
    server_url: "https://ntfy.sh"
    token: "tk_your_access_token"

Get an access token:

1. Go to https://ntfy.sh/account
2. Create an account or log in
3. Go to "Access Tokens"
4. Create a new token with appropriate permissions
5. Copy the token (starts with tk_)

Publish Tokens (for specific topics)

notifiers:
  ntfy:
    server_url: "https://ntfy.sh"
    token: "your_publish_token"

Create a publish token:

1. Create a topic with reserved access
2. Generate a publish token for that topic
3. Use the token in your configuration

2. Basic Authentication

Alternative to token auth:

notifiers:
  ntfy:
    server_url: "https://ntfy.sh"
    username: "your-username"
    password: "your-password"

3. No Authentication (Public Topics)

For public topics on ntfy.sh:

notifiers:
  ntfy:
    server_url: "https://ntfy.sh"
    # No token, username, or password needed

Configuration Options

Full Configuration Example

notifiers:
  ntfy:
    # Server URL (default: https://ntfy.sh)
    server_url: "https://ntfy.sh"

    # Authentication (choose one method)
    token: "tk_your_token"              # Token auth (recommended)
    # username: "user"                  # Or basic auth
    # password: "pass"

    # Optional: default topic if not specified in notification
    default_topic: "my-default-topic"

    # Optional: skip TLS verification (for self-hosted with self-signed certs)
    insecure_skip_verify: false

Self-Hosted Ntfy Server

notifiers:
  ntfy:
    server_url: "https://ntfy.yourcompany.com"
    token: "your_custom_token"
    # For self-signed certificates
    insecure_skip_verify: true

Sending Notifications

Basic Notification

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Hello from Notifier!",
    "body": "This is a test notification",
    "recipients": ["my-topic"]
  }'

With Priority

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "priority": 4,
    "subject": "CRITICAL Alert",
    "body": "Something important happened!",
    "recipients": ["alerts"]
  }'

Priority mapping:

• 0 (Low) → ntfy priority 2
• 1 (Normal) → ntfy priority 3 (default)
• 2 (High) → ntfy priority 4
• 3 (Critical) → ntfy priority 5 (max)

With Tags (Emojis)

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Deployment Complete",
    "body": "Application deployed successfully",
    "recipients": ["deployments"],
    "metadata": {
      "tags": ["rocket", "tada", "white_check_mark"]
    }
  }'

Common tags:

• warning, rotating_light, skull - Alerts
• tada, rocket, sparkles - Success
• x, no_entry, stop_sign - Errors
• information_source, eyes - Info

With Click Action

Make the notification clickable:

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "New Pull Request",
    "body": "PR #123 needs review",
    "recipients": ["github-notifications"],
    "metadata": {
      "click": "https://github.com/your-org/your-repo/pull/123",
      "tags": ["github"]
    }
  }'

With Attachment

Attach an image or file:

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Server Stats",
    "body": "Current server metrics",
    "recipients": ["monitoring"],
    "metadata": {
      "attach": "https://example.com/metrics.png",
      "tags": ["chart_with_upwards_trend"]
    }
  }'

With Custom Icon

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Custom Notification",
    "body": "With a custom icon",
    "recipients": ["custom-alerts"],
    "metadata": {
      "icon": "https://example.com/logo.png"
    }
  }'

With Delayed Delivery

Schedule notification for later:

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Reminder",
    "body": "Meeting in 30 minutes",
    "recipients": ["reminders"],
    "metadata": {
      "delay": "30m",
      "tags": ["alarm_clock"]
    }
  }'

Delay formats:

• 30s - 30 seconds
• 5m - 5 minutes
• 2h - 2 hours
• tomorrow 10am - Tomorrow at 10 AM

With Action Buttons

Add interactive buttons:

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Deploy to Production?",
    "body": "Version 2.0 is ready",
    "recipients": ["deployments"],
    "metadata": {
      "actions": [
        {
          "action": "view",
          "label": "View Release",
          "url": "https://github.com/your-org/your-repo/releases/v2.0",
          "clear": true
        },
        {
          "action": "http",
          "label": "Deploy",
          "url": "https://api.yourcompany.com/deploy",
          "body": "{\"version\": \"2.0\"}",
          "clear": true
        }
      ]
    }
  }'

Action types:

• view - Open a URL
• http - Send HTTP request
• broadcast - Android broadcast intent

With Email Forwarding

Forward to email (requires ntfy.sh tier 2+):

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "Important Alert",
    "body": "This will also be sent via email",
    "recipients": ["alerts"],
    "metadata": {
      "email": "admin@example.com",
      "tags": ["email"]
    }
  }'

Multiple Topics

Send to multiple topics:

curl -X POST http://localhost:8080/api/v1/notifications \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ntfy",
    "subject": "System Update",
    "body": "System will restart in 5 minutes",
    "recipients": ["admins", "monitoring", "alerts"],
    "metadata": {
      "tags": ["warning"]
    }
  }'

Mobile App Setup

iOS

1. Download ntfy from the App Store
2. Add a topic subscription
3. Use the same topic name in your notifications

Android

1. Download ntfy from Google Play or F-Droid
2. Add a topic subscription
3. Configure notification settings
4. Use the same topic name in your notifications

Desktop (Linux/macOS/Windows)

# Install ntfy CLI
curl -sSL https://ntfy.sh/install.sh | sh

# Subscribe to topics
ntfy subscribe mytopic

Topic Naming Best Practices

Public Topics

• Use unique, hard-to-guess names
• Consider including random strings: myapp-alerts-x7k9p2
• Anyone who knows the name can subscribe

Private Topics (Recommended)

• Requires authentication
• Create reserved topics on ntfy.sh
• Use access control lists (ACLs)

Topic Organization

# Example topic structure
- myapp-prod-alerts      # Production alerts
- myapp-prod-info        # Production info
- myapp-staging-alerts   # Staging alerts
- myapp-ci-cd            # CI/CD notifications
- myapp-monitoring       # Monitoring metrics

Environment Variables

Override configuration with environment variables:

export NOTIFIER_NOTIFIERS_NTFY_SERVER_URL=https://ntfy.yourcompany.com
export NOTIFIER_NOTIFIERS_NTFY_TOKEN=tk_your_token
export NOTIFIER_NOTIFIERS_NTFY_DEFAULT_TOPIC=default-topic
export NOTIFIER_NOTIFIERS_NTFY_INSECURE_SKIP_VERIFY=false

Security Considerations

Token Security

• Never commit tokens to version control
• Store tokens in Kubernetes Secrets or environment variables
• Rotate tokens regularly
• Use publish tokens with limited scope when possible

Topic Security

• Use reserved/private topics for sensitive data
• Don't include secrets in notification bodies
• Consider encryption for highly sensitive data
• Use unique topic names to prevent enumeration

Self-Hosted Servers

• Use TLS with valid certificates
• Enable authentication
• Configure rate limiting
• Monitor access logs
• Keep ntfy server updated

Kubernetes Deployment

Using Secrets

apiVersion: v1
kind: Secret
metadata:
  name: notifier-secrets
type: Opaque
stringData:
  ntfy-token: "tk_your_access_token"

Deployment Configuration

env:
- name: NOTIFIER_NOTIFIERS_NTFY_TOKEN
  valueFrom:
    secretKeyRef:
      name: notifier-secrets
      key: ntfy-token

Rate Limits

ntfy.sh Free Tier

• 250 messages/day per visitor
• Unlimited topics
• Message retention: 12 hours

ntfy.sh Tier 1 ($5/month)

• 500 messages/day
• Message retention: 1 day
• Attachment & email support

ntfy.sh Tier 2 ($10/month)

• 1000 messages/day
• Message retention: 7 days
• Higher attachment limits

Self-Hosted

• Configure your own limits
• Full control over retention
• No external dependencies

Troubleshooting

Authentication Errors

Error: ntfy server returned status: 401

Solution: Verify token is correct and has necessary permissions

Topic Not Found

Error: ntfy server returned status: 404

Solution: Check topic name spelling, ensure topic exists if using reserved topics

TLS Errors (Self-Hosted)

Error: x509: certificate signed by unknown authority

Solution: Either fix certificate or set insecure_skip_verify: true (not recommended for production)

Rate Limit Exceeded

Error: ntfy server returned status: 429

Solution: Reduce message frequency or upgrade ntfy.sh tier

Connection Timeout

Error: context deadline exceeded

Solution: Check network connectivity, firewall rules, or server URL

Examples

See QUICKSTART.md for more examples of using ntfy with the Notifier service.

Resources

• Ntfy Documentation
• Ntfy.sh Public Instance
• Self-Hosting Guide
• API Reference