Introduction

Ntfy.sh is an open-source service that simplifies push notifications by offering a free-to-use HTTP-based API. With it, you can easily send messages or alerts to phones, desktops, or other devices via HTTP POST/PUT requests, without the need for API keys or complex setups.

In this post, we’ll walk through the basics of Ntfy.sh, followed by example code in Go, Python, and JavaScript. We’ll also explore additional features like message retention, attachments, and end-to-end encryption.

Why Ntfy.sh?

Ntfy.sh stands out for its simplicity and flexibility:

  • Free and open-source: Hosted version available at ntfy.sh, or self-host on your server.
  • No API keys: You simply use topics as endpoints (e.g., https://ntfy.sh/mytopic).
  • Real-time notifications: Perfect for alerts or status updates in DevOps, home automation, or simple app monitoring.
  • Mobile app integration: Install the Ntfy app for iOS or Android to receive notifications directly on your phone.

Basic Ntfy.sh Usage

Ntfy.sh operates on a pub-sub model, where the URL path acts as the topic (like a channel). Sending messages is as simple as an HTTP POST request, while subscribers receive notifications by listening to the same topic.

Example: Sending a Notification via CURL

curl -d "Backup completed successfully!" ntfy.sh/mytopic

This command sends a message to the topic mytopic, which can then be received by anyone subscribed to the topic.

Advanced Features

  1. Message Retention:
    Messages sent to Ntfy.sh can be retained for up to 7 days if you set the X-Message-Ttl header.

    curl -d "This is a retained message" -H "X-Message-Ttl: 86400" ntfy.sh/mytopic

  2. File Attachments:
    You can send files along with your notifications.

    curl -F file=@/path/to/file.txt ntfy.sh/mytopic

  3. End-to-End Encryption (E2EE):
    For enhanced privacy, Ntfy supports E2EE. Encryption happens on the client side using a secret password, and only the recipient who knows the password can decrypt the message.

    curl -d "This is a secret message" -H "X-Encryption-Key: mysecret" ntfy.sh/mytopic

Code Examples

1. Sending Notifications in Go

package main

import (
    "bytes"
    "net/http"
    "log"
)

func main() {
    url := "https://ntfy.sh/mytopic"
    message := []byte("Backup successful")

    req, err := http.NewRequest("POST", url, bytes.NewBuffer(message))
    if err != nil {
        log.Fatal(err)
    }

    req.Header.Set("Content-Type", "text/plain")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    log.Println("Notification sent:", resp.Status)
}

This Go example sends a message to the mytopic topic using the standard net/http package.

2. Sending Notifications in Python

import requests

url = "https://ntfy.sh/mytopic"
message = "Backup successful"

response = requests.post(url, data=message)

if response.status_code == 200:
    print("Notification sent successfully!")
else:
    print(f"Failed to send notification: {response.status_code}")

With Python, the requests library makes it easy to send a POST request. Here, we send a message to the mytopic topic, and the script prints a success message if the response is successful.

3. Sending Notifications in JavaScript (Node.js)

const https = require('https');

const data = 'Backup successful';
const options = {
  hostname: 'ntfy.sh',
  port: 443,
  path: '/mytopic',
  method: 'POST',
  headers: {
    'Content-Type': 'text/plain',
    'Content-Length': data.length,
  },
};

const req = https.request(options, (res) => {
  console.log(`Status: ${res.statusCode}`);
});

req.on('error', (e) => {
  console.error(`Problem with request: ${e.message}`);
});

req.write(data);
req.end();

In this Node.js example, we send a notification to Ntfy using the https module, which works similarly to the Python and Go examples.

Additional Use Cases

1. Monitoring Server Health

Use Ntfy.sh to alert you when critical system events happen (e.g., disk space warnings, service failures).

df -h | grep /dev/sda1 | awk '{if($5>80) system("curl -d \"Disk space low\" ntfy.sh/admin")}'

2. Home Automation

Send a notification when your smart devices trigger certain actions (e.g., when your doorbell rings).

# Example for smart doorbell:
if doorbell_pressed:
    requests.post("https://ntfy.sh/home", data="Someone is at the door!")

Conclusion

Ntfy.sh is a versatile, lightweight, and open-source notification service. Whether you’re automating a server alert, sending a personal reminder, or integrating it into a larger system, Ntfy.sh provides an intuitive API for developers. Its support for attachments, message retention, and encryption makes it a valuable tool for a variety of applications.

For more information or advanced usage, visit the official Ntfy documentation.