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 or cost. It's also open source if you want to run your own.

There are many ways to use ntfy. You can send yourself messages for all sorts of things: When a long process finishes or fails (a backup, a long rsync job, ...), or to notify yourself when somebody logs into your server(s). Or you may want to use it in your own app to distribute messages to subscribed clients. Endless possibilities 😀.

Publishing messages

Publishing messages can be done via PUT or POST using. 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 curl:

curl -d "long process is done" 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.'
})

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 via Android App

You can use the Ntfy Android App to receive notifications directly on your phone. Just like the server, this app is also open source.

Subscribe via your app, or via the CLI

Using EventSource in JS, you can consume notifications like this (see full 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

Here's an example of how to use this endpoint to send desktop notifications for every incoming message:

while read msg; do
  [ -n "$msg" ] && notify-send "$msg"
done < <(stdbuf -i0 -o0 curl -s ntfy.sh/mytopic/raw)

Message buffering and polling

Messages are buffered in memory for a few hours 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) or a Unix timestamp (e.g. 1635528757):

$ curl -s "ntfy.sh/mytopic/json?since=10m"
# Same output as above, but includes messages from up to 10 minutes ago

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 has to be combined with since=.

$ curl -s "ntfy.sh/mytopic/json?poll=1&since=10m"
# Returns messages from up to 10 minutes ago and ends the connection

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.

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. Check the code if you don't believe me.

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. I tried really, really hard to avoid using FCM, but newer versions of Android made it impossible to implement background services.

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 (up to a day) to support service restarts.

Made with ❤️ by Philipp C. Heckel