ntfy.sh | simple HTTP-based pub-sub
ntfy (pronounce: notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, entirely without signup, cost or setup. It's also open source if you want to run your own.
There are many ways to use it: Notify yourself when a build finishes, when an rsync is done or a backup fails, or know when somebody logs into your server. There are many more examples, endless possibilities 😀.
Publishing messages
Publishing messages can be done via PUT or POST. Topics are created on the fly by subscribing or publishing to them. Because there is no sign-up, the topic is essentially a password, so pick something that's not easily guessable.
Here's an example showing how to publish a message using a POST request (via curl -d):
curl -d "Backup successful 😀" ntfy.sh/mytopic
Here's an example in JS with fetch() (see full example):
fetch('https://ntfy.sh/mytopic', {
method: 'POST', // PUT works too
body: 'Hello from the other side.'
})
There are more features related to publishing messages: You can set a notification priority, a title, and tag messages. Here's an example using all of them:
curl \
-H "Title: Unauthorized access detected" \
-H "Priority: urgent" \
-H "Tags: warning,skull" \
-d "Remote access to $(hostname) detected. Act right away." \
ntfy.sh/mytopic
Subscribe to a topic
You can create and subscribe to a topic either in this web UI, or in your own app by subscribing to an EventSource, a JSON feed, or raw feed.
Subscribe in this Web UI
Subscribe to topics here and receive messages as desktop notification. Topics are not password-protected, so choose a name that's not easy to guess. Once subscribed, you can publish messages via PUT/POST.
Subscribe from your phone
You can use the Ntfy Android App to receive notifications directly on your phone. Just like the server, this app is also open source. Since I don't have an iPhone or a Mac, I didn't make an iOS app yet. I'd be awesome if someone else could help out.
Subscribe via your app, or via the CLI
Using EventSource in JS, you can consume notifications like this (see live example):
const eventSource = new EventSource('https://ntfy.sh/mytopic/sse');
eventSource.onmessage = (e) => {
// Do something with e.data
};
You can also use the same /sse endpoint via curl or any other HTTP library:
$ curl -s ntfy.sh/mytopic/sse
event: open
data: {"id":"weSj9RtNkj","time":1635528898,"event":"open","topic":"mytopic"}
data: {"id":"p0M5y6gcCY","time":1635528909,"event":"message","topic":"mytopic","message":"Hi!"}
event: keepalive
data: {"id":"VNxNIg5fpt","time":1635528928,"event":"keepalive","topic":"test"}
To consume JSON instead, use the /json endpoint, which prints one message per line:
$ curl -s ntfy.sh/mytopic/json
{"id":"SLiKI64DOt","time":1635528757,"event":"open","topic":"mytopic"}
{"id":"hwQ2YpKdmg","time":1635528741,"event":"message","topic":"mytopic","message":"Hi!"}
{"id":"DGUDShMCsc","time":1635528787,"event":"keepalive","topic":"mytopic"}
Or use the /raw endpoint if you need something super simple (empty lines are keepalive messages):
$ curl -s ntfy.sh/mytopic/raw
This is a notification
And another one with a smiley face 😀
Other features
Fetching cached messages (since=)
Messages are cached on disk for {{.CacheDuration}} to account for network interruptions of subscribers. You can read back what you missed by using the since= query parameter. It takes either a duration (e.g. 10m or 30s), a Unix timestamp (e.g. 1635528757) or all (all cached messages).
curl -s "ntfy.sh/mytopic/json?since=10m"
Polling (poll=1)
You can also just poll for messages if you don't like the long-standing connection using the poll=1 query parameter. The connection will end after all available messages have been read. This parameter can be combined with since= (defaults to since=all).
curl -s "ntfy.sh/mytopic/json?poll=1"
Subscribing to multiple topics (topic1,topic2,...)
It's possible to subscribe to multiple topics in one HTTP call by providing a comma-separated list of topics in the URL. This allows you to reduce the number of connections you have to maintain:
$ curl -s ntfy.sh/mytopic1,mytopic2/json
{"id":"0OkXIryH3H","time":1637182619,"event":"open","topic":"mytopic1,mytopic2,mytopic3"}
{"id":"dzJJm7BCWs","time":1637182634,"event":"message","topic":"mytopic1","message":"for topic 1"}
{"id":"Cm02DsxUHb","time":1637182643,"event":"message","topic":"mytopic2","message":"for topic 2"}
Message priority (X-Priority, Priority, prio, or p)
All messages have a priority, which defines how your urgently your phone notifies you. You can set custom notification sounds and vibration patterns on your phone to map to these priorities.
The following priorities exist: 1 (min), 2 (low), 3 (default), 4 (high), and 5 (max/urgent). You can set the priority with the header X-Priority (or any of its aliases: Priority, prio, or p). Here are a few examples:
curl -H "X-Priority: urgent" -d "An urgent message" ntfy.sh/mytopic
curl -H "Priority: 2" -d "Low priority message" ntfy.sh/mytopic
curl -H p:4 -d "A high priority message" ntfy.sh/mytopic
Notification title (X-Title, Title, ti, or t)
The notification title is typically set to the topic short URL (e.g. ntfy.sh/mytopic. To override it, you can set the X-Title header (or any of its aliases: Title, ti, or t).
curl -H "Title: Dogs are better than cats" -d "Oh my ..." ntfy.sh/mytopic
Tags & emojis 🥳 🎉 (X-Tags, Tags, or ta)
You can tag messages with emojis (or other relevant strings). If a tag matches a known emoji short code, it will be converted to an emoji. If it doesn't match, it will be listed below the notification. This is useful for things like warnings and such (⚠️, ️🚨, or 🚩), but also to simply tag messages otherwise (e.g. which script the message came from, ...).
You can set tags with the X-Tags header (or any of its aliases: Tags, or ta). Use this reference to figure out what tags can be converted to emojis. In the example below, the tag "warning" matches the emoji ⚠️, the tag "ssh-login" doesn't match and will be displayed below the message.
$ curl -H "Tags: warning,ssh-login" -d "Unauthorized SSH access" ntfy.sh/mytopic
{"id":"ZEIwjfHlSS",...,"tags":["warning","ssh-login"],"message":"Unauthorized SSH access"}
Examples
There are a million ways to use ntfy, but here are some inspirations. I try to collect examples on GitHub, so be sure to check those out, too.
Example: A long process is done: backups, copying data, pipelines, ...
I started adding notifications pretty much all of my scripts. Typically, I just chain the curl call directly to the command I'm running. The following example will either send Laptop backup succeeded or ⚠️ Laptop backup failed directly to my phone:
rsync -a root@laptop /backups/laptop \
&& zfs snapshot ... \
&& curl -d "Laptop backup succeeded" ntfy.sh/backups \
|| curl -H tags:warning -H prio:high -d "Laptop backup failed" ntfy.sh/backups
Example: Server-sent messages in your web app
Just as you can subscribe to topics in this Web UI, you can use ntfy in your own web application. Check out the live example or just look the source of this page.
Example: Notify on SSH login
Years ago my home server was broken into. That shook me hard, so every time someone logs into any machine that I own, I now message myself. Here's an example of how to use PAM to notify yourself on SSH login.
/etc/pam.d/sshd (at the end of the file):
session optional pam_exec.so /usr/local/bin/ntfy-ssh-login.sh
/usr/local/bin/ntfy-ssh-login.sh:
#!/bin/bash
if [ "${PAM_TYPE}" = "open_session" ]; then
curl -H tags:warning -d "SSH login: ${PAM_USER} from ${PAM_RHOST}" ntfy.sh/alerts
fi
Example: Collect data from multiple machines
The other day I was running tasks on 20 servers and I wanted to collect the interim results as a CSV in one place. Here's the script I wrote:
while read result; do
[ -n "$result" ] && echo "$result" >> results.csv
done < <(stdbuf -i0 -o0 curl -s ntfy.sh/results/raw)
FAQ
Isn't this like ...?
Who knows. I didn't do a lot of research before making this. It was fun making it.
Can I use this in my app? Will it stay free?
Yes. As long as you don't abuse it, it'll be available and free of charge. I do not plan on monetizing
the service.
What are the uptime guarantees?
Best effort.
What happens if there are multiple subscribers to the same topic?
As per usual with pub-sub, all subscribers receive notifications if they are
subscribed to a topic.
Will you know what topics exist, can you spy on me?
If you don't trust me or your messages are sensitive, run your own server. It's open source.
That said, the logs do not contain any topic names or other details about you.
Messages are cached for {{.CacheDuration}} to facilitate service restarts, message polling and to overcome
client network disruptions.
Can I self-host it?
Yes. The server (including this Web UI) can be self-hosted, and the Android app supports adding topics from
your own server as well. There are install instructions
on GitHub.
Why is Firebase used?
In addition to caching messages locally and delivering them to long-polling subscribers, all messages are also
published to Firebase Cloud Messaging (FCM) (if FirebaseKeyFile is set, which it is on ntfy.sh). This
is to facilitate instant notifications on Android.
How much battery does the Android app use?
If you use the ntfy.sh server and you don't use the instant delivery feature, the Android app uses no
additional battery, since Firebase Cloud Messaging (FCM) is used. If you use your own server, or you use
instant delivery, the app has to maintain a constant connection to the server, which consumes about 4% of
battery in 17h of use (on my phone). I use it and it makes no difference to me.
What is instant delivery?
Instant delivery is a feature in the Android app. If turned on, the app maintains a constant connection to the
server and listens for incoming notifications. This consumes additional battery,
but delivers notifications instantly.
Why is there no iOS app (yet)?
I don't have an iPhone or a Mac, so I didn't make an iOS app yet. It'd be awesome if
someone else could help out.
Privacy policy
Neither the server nor the app record any personal information, or share any of the messages and topics with any outside service. All data is exclusively used to make the service function properly. The one exception is the Firebase Cloud Messaging (FCM) service, which is required to provide instant Android notifications (see FAQ for details).
The web server does not log or otherwise store request paths, remote IP addresses or even topics or messages, aside from a short on-disk cache (for {{.CacheDuration}}) to support service restarts.