2021-11-08 15:24:34 +01:00
{{- /*gotype: heckel.io/ntfy/server.indexPage*/ -}}
2021-10-23 03:26:01 +02:00
<!DOCTYPE html>
<html lang="en">
<head>
2021-10-24 20:22:53 +02:00
<meta charset="UTF-8">
<title>ntfy.sh | simple HTTP-based pub-sub</title>
<link rel="stylesheet" href="static/css/app.css" type="text/css">
<!-- Mobile view -->
<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="HandheldFriendly" content="true">
<!-- Mobile browsers, background color -->
2021-11-12 20:43:32 +01:00
<meta name="theme-color" content="#317f6f">
<meta name="msapplication-navbutton-color" content="#317f6f">
<meta name="apple-mobile-web-app-status-bar-style" content="#317f6f">
2021-10-24 20:22:53 +02:00
<!-- Favicon, see favicon.io -->
<link rel="icon" type="image/png" href="static/img/favicon.png">
<!-- Previews in Google, Slack, WhatsApp, etc. -->
<meta property="og:type" content="website" />
<meta property="og:locale" content="en_US" />
<meta property="og:site_name" content="ntfy.sh" />
<meta property="og:title" content="ntfy.sh | simple HTTP-based pub-sub" />
<meta property="og:description" content="ntfy is a simple HTTP-based pub-sub notification service. It allows you to send desktop notifications via scripts from any computer, entirely without signup or cost. Made with ❤ by Philipp C. Heckel, Apache License 2.0, source at https://heckel.io/ntfy." />
2021-10-31 04:46:08 +01:00
<meta property="og:image" content="/static/img/ntfy.png" />
2021-10-24 20:22:53 +02:00
<meta property="og:url" content="https://ntfy.sh" />
2021-11-08 15:24:34 +01:00
{{if .Topic}}
<!-- Never index topic page -->
<meta name="robots" content="noindex, nofollow" />
{{end}}
2021-10-23 03:26:01 +02:00
</head>
<body>
2021-11-08 15:24:34 +01:00
<div id="main"{{if .Topic}} style="display: none"{{end}}>
<h1><img src="static/img/ntfy.png" alt="ntfy"/><br/>ntfy.sh | simple HTTP-based pub-sub</h1>
2021-10-24 03:29:45 +02:00
<p>
2021-11-08 15:24:34 +01:00
<b>Ntfy</b> (pronounce: <i>notify</i>) is a simple HTTP-based <a href="https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern">pub-sub</a> notification service.
2021-11-18 15:22:33 +01:00
It allows you to send notifications <a href="#subscribe-phone">to your phone</a> or desktop via scripts from any computer,
2021-11-04 15:55:34 +01:00
entirely <b>without signup or cost</b>. It's also <a href="https://github.com/binwiederhier/ntfy">open source</a> if you want to run your own.
2021-10-24 03:29:45 +02:00
</p>
2021-11-09 16:46:47 +01:00
<div id="screenshots">
<a href="static/img/screenshot-curl.png"><img src="static/img/screenshot-curl.png"/></a>
<a href="static/img/screenshot-web-detail.png"><img src="static/img/screenshot-web-detail.png"/></a>
<span class="nowrap">
<a href="static/img/screenshot-phone-main.jpg"><img src="static/img/screenshot-phone-main.jpg"/></a>
<a href="static/img/screenshot-phone-detail.jpg"><img src="static/img/screenshot-phone-detail.jpg"/></a>
<a href="static/img/screenshot-phone-notification.jpg"><img src="static/img/screenshot-phone-notification.jpg"/></a>
</span>
</div>
2021-11-05 03:47:29 +01:00
<p>
2021-11-18 15:22:33 +01:00
There are many ways to use Ntfy. You can send yourself messages for all sorts of things: When a long process finishes or fails,
2021-11-05 03:47:29 +01:00
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.
2021-11-18 15:22:33 +01:00
Endless possibilities 😀. Be sure to check out the <a href="#examples">examples below</a>.
2021-11-05 03:47:29 +01:00
</p>
2021-10-23 03:26:01 +02:00
2021-11-18 02:50:47 +01:00
<h2 id="publish" class="anchor">Publishing messages</h2>
2021-10-24 03:29:45 +02:00
<p>
2021-11-18 19:14:55 +01:00
Publishing messages can be done via PUT or POST. Topics are created on the fly by subscribing or publishing to them.
2021-10-29 19:58:14 +02:00
Because there is no sign-up, <b>the topic is essentially a password</b>, so pick something that's not easily guessable.
</p>
<p class="smallMarginBottom">
2021-11-18 19:14:55 +01:00
Here's an example showing how to publish a message using <tt>curl</tt> (via POST):
2021-10-29 19:58:14 +02:00
</p>
<code>
2021-11-18 19:14:55 +01:00
curl -d "Backup successful 😀" ntfy.sh/mytopic
</code>
<p class="smallMarginBottom">
And another one using PUT:
</p>
<code>
echo -en "\u26A0\uFE0F Unauthorized login" | curl -sT- ntfy.sh/mytopic
2021-10-29 19:58:14 +02:00
</code>
<p class="smallMarginBottom">
Here's an example in JS with <tt>fetch()</tt> (see <a href="https://github.com/binwiederhier/ntfy/tree/main/examples">full example</a>):
2021-10-24 04:49:50 +02:00
</p>
2021-10-29 19:58:14 +02:00
<code>
fetch('https://ntfy.sh/mytopic', {<br/>
method: 'POST', // PUT works too<br/>
body: 'Hello from the other side.'<br/>
})
</code>
2021-11-18 02:50:47 +01:00
<h2 id="subscribe" class="anchor">Subscribe to a topic</h2>
2021-10-24 04:49:50 +02:00
<p>
2021-10-29 19:58:14 +02:00
You can create and subscribe to a topic either in this web UI, or in your own app by subscribing to an
<a href="https://developer.mozilla.org/en-US/docs/Web/API/EventSource">EventSource</a>, a JSON feed, or raw feed.
2021-10-24 03:29:45 +02:00
</p>
2021-10-23 03:26:01 +02:00
2021-11-04 15:55:34 +01:00
<div id="subscribeBox">
2021-11-18 02:50:47 +01:00
<h3 id="subscribe-web" class="anchor">Subscribe in this Web UI</h3>
2021-11-05 03:32:17 +01:00
<p id="error"></p>
<p>
Subscribe to topics here and receive messages as <b>desktop notification</b>. Topics are not password-protected,
so choose a name that's not easy to guess. Once subscribed, you can publish messages via PUT/POST.
</p>
2021-11-04 15:55:34 +01:00
<form id="subscribeForm">
<p>
2021-11-05 03:32:17 +01:00
<b>Topic:</b><br/>
2021-11-08 15:24:34 +01:00
<input type="text" id="topicField" autocomplete="off" placeholder="Topic name, e.g. phil_alerts" maxlength="64" pattern="[-_A-Za-z0-9]{1,64}" />
2021-11-04 15:55:34 +01:00
<button id="subscribeButton">Subscribe</button>
</p>
2021-11-05 03:32:17 +01:00
<p id="topicsHeader"><b>Subscribed topics:</b></p>
<ul id="topicsList"></ul>
2021-11-04 15:55:34 +01:00
</form>
<audio id="notifySound" src="static/sound/mixkit-message-pop-alert-2354.mp3"></audio>
</div>
2021-10-24 03:29:45 +02:00
2021-11-18 15:22:33 +01:00
<h3 id="subscribe-phone" class="anchor">Subscribe from your phone</h3>
2021-11-01 21:39:40 +01:00
<p>
2021-11-03 16:33:34 +01:00
You can use the <a href="https://play.google.com/store/apps/details?id=io.heckel.ntfy">Ntfy Android App</a>
to receive notifications directly on your phone. Just like the server, this app is also <a href="https://github.com/binwiederhier/ntfy-android">open source</a>.
2021-11-18 15:22:33 +01:00
Since I don't have an iPhone or a Mac, I didn't make an iOS app yet. I'd be awesome if <a href="https://github.com/binwiederhier/ntfy/issues/4">someone else could help out</a>.
</p>
<p>
<a href="https://play.google.com/store/apps/details?id=io.heckel.ntfy"><img src="static/img/badge-googleplay.png"></a>
<a href="https://github.com/binwiederhier/ntfy/issues/4"><img src="static/img/badge-appstore.png"></a>
2021-11-01 21:39:40 +01:00
</p>
2021-11-18 02:50:47 +01:00
<h3 id="subscribe-api" class="anchor">Subscribe via your app, or via the CLI</h3>
2021-10-27 20:56:17 +02:00
<p class="smallMarginBottom">
2021-10-29 19:58:14 +02:00
Using <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventSource">EventSource</a> in JS, you can consume
2021-11-18 15:22:33 +01:00
notifications like this (see <a href="example.html">live example</a>):
2021-10-25 04:08:06 +02:00
</p>
<code>
2021-10-25 14:54:46 +02:00
const eventSource = new EventSource('https://ntfy.sh/mytopic/sse');<br/>
2021-10-25 04:08:06 +02:00
eventSource.onmessage = (e) => {<br/>
// Do something with e.data<br/>
};
2021-10-24 20:22:53 +02:00
</code>
2021-10-27 20:56:17 +02:00
<p class="smallMarginBottom">
2021-10-29 19:58:14 +02:00
You can also use the same <tt>/sse</tt> endpoint via <tt>curl</tt> or any other HTTP library:
2021-10-27 20:56:17 +02:00
</p>
<code>
$ curl -s ntfy.sh/mytopic/sse<br/>
event: open<br/>
2021-10-29 19:58:14 +02:00
data: {"id":"weSj9RtNkj","time":1635528898,"event":"open","topic":"mytopic"}<br/><br/>
2021-10-27 20:56:17 +02:00
2021-10-29 19:58:14 +02:00
data: {"id":"p0M5y6gcCY","time":1635528909,"event":"message","topic":"mytopic","message":"Hi!"}<br/><br/>
2021-10-27 20:56:17 +02:00
event: keepalive<br/>
2021-10-29 19:58:14 +02:00
data: {"id":"VNxNIg5fpt","time":1635528928,"event":"keepalive","topic":"test"}
</code>
<p class="smallMarginBottom">
To consume JSON instead, use the <tt>/json</tt> endpoint, which prints one message per line:
</p>
<code>
$ curl -s ntfy.sh/mytopic/json<br/>
{"id":"SLiKI64DOt","time":1635528757,"event":"open","topic":"mytopic"}<br/>
{"id":"hwQ2YpKdmg","time":1635528741,"event":"message","topic":"mytopic","message":"Hi!"}<br/>
{"id":"DGUDShMCsc","time":1635528787,"event":"keepalive","topic":"mytopic"}
2021-10-27 20:56:17 +02:00
</code>
<p class="smallMarginBottom">
2021-10-29 19:58:14 +02:00
Or use the <tt>/raw</tt> endpoint if you need something super simple (empty lines are keepalive messages):
2021-10-27 20:56:17 +02:00
</p>
<code>
$ curl -s ntfy.sh/mytopic/raw<br/>
<br/>
2021-11-18 15:22:33 +01:00
This is a notification<br/>
And another one with a smiley face 😀
2021-11-05 03:47:29 +01:00
</code>
2021-10-24 04:49:50 +02:00
2021-11-18 02:50:47 +01:00
<h2 id="other-features" class="anchor">Other features</h2>
2021-11-18 15:22:33 +01:00
<h3 id="fetching-cached-messages" class="anchor">Fetching cached messages (<tt>since=</tt>)</h3>
2021-10-27 20:56:17 +02:00
<p class="smallMarginBottom">
2021-11-18 02:50:47 +01:00
Messages are cached on disk for {{.CacheDuration}} to account for network interruptions of subscribers.
You can read back what you missed by using the <tt>since=</tt> query parameter. It takes either a
duration (e.g. <tt>10m</tt> or <tt>30s</tt>), a Unix timestamp (e.g. <tt>1635528757</tt>) or <tt>all</tt> (all
cached messages).
2021-10-24 04:49:50 +02:00
</p>
2021-10-24 20:22:53 +02:00
<code>
2021-11-18 02:50:47 +01:00
curl -s "ntfy.sh/mytopic/json?since=10m"
2021-10-24 20:22:53 +02:00
</code>
2021-11-18 02:50:47 +01:00
2021-11-18 15:22:33 +01:00
<h3 id="polling" class="anchor">Polling (<tt>poll=1</tt>)</h3>
2021-10-27 20:56:17 +02:00
<p class="smallMarginBottom">
2021-10-29 19:58:14 +02:00
You can also just poll for messages if you don't like the long-standing connection using the <tt>poll=1</tt>
2021-11-18 02:50:47 +01:00
query parameter. The connection will end after all available messages have been read. This parameter can be
combined with <tt>since=</tt> (defaults to <tt>since=all</tt>).
2021-10-25 04:08:06 +02:00
</p>
<code>
2021-11-18 02:50:47 +01:00
curl -s "ntfy.sh/mytopic/json?poll=1"
2021-10-25 04:08:06 +02:00
</code>
2021-11-01 21:39:40 +01:00
2021-11-18 15:22:33 +01:00
<h3 id="multiple-topics" class="anchor">Subscribing to multiple topics (<tt>topic1,topic2,...</tt>)</h3>
2021-11-18 02:50:47 +01:00
<p class="smallMarginBottom">
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:
</p>
<code>
$ curl -s ntfy.sh/mytopic1,mytopic2/json<br/>
{"id":"0OkXIryH3H","time":1637182619,"event":"open","topic":"mytopic1,mytopic2,mytopic3"}<br/>
{"id":"dzJJm7BCWs","time":1637182634,"event":"message","topic":"mytopic1","message":"for topic 1"}<br/>
{"id":"Cm02DsxUHb","time":1637182643,"event":"message","topic":"mytopic2","message":"for topic 2"}
</code>
2021-11-18 15:22:33 +01:00
<h2 id="examples" class="anchor">Examples</h2>
<p>
There are a million ways to use Ntfy, but here are some inspirations. I try to collect
<a href="https://github.com/binwiederhier/ntfy/tree/main/examples">examples on GitHub</a>, so be sure to check
those out, too.
</p>
<h3 id="example-alerts" class="anchor">Example: A long process is done: backups, copying data, pipelines, ...</h3>
<p class="smallMarginBottom">
I started adding notifications pretty much all of my scripts. Typically, I just chain the <tt>curl</tt> call
directly to the command I'm running. The following example will either send <i>Laptop backup succeeded</i>
or ⚠️ <i>Laptop backup failed</i> directly to my phone:
</p>
<code>
rsync -a root@laptop /backups/laptop \<br/>
&& zfs snapshot ... \<br/>
&& curl -d "Laptop backup succeeded" ntfy.sh/backups \<br/>
|| echo -en "\u26A0\uFE0F Laptop backup failed" | curl -sT- ntfy.sh/backups
</code>
<h3 id="example-web" class="anchor">Example: Server-sent messages in your web app</h3>
<p>
Just as you can <a href="#subscribe-web">subscribe to topics in this Web UI</a>, you can use Ntfy in your own
web application. Check out the <a href="example.html">live example</a> or just look the source of this page.
</p>
<h3 id="example-notify-ssh" class="anchor">Example: Notify on SSH login</h3>
<p>
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 <a href="https://en.wikipedia.org/wiki/Linux_PAM">PAM</a>
to notify yourself on SSH login.
</p>
<p class="smallMarginBottom">
<b>/etc/pam.d/sshd</b> (at the end of the file):
</p>
<code>
session optional pam_exec.so /usr/local/bin/ntfy-ssh-login.sh
</code>
<p class="smallMarginBottom">
<b>/usr/local/bin/ntfy-ssh-login.sh</b>:
</p>
<code>
#!/bin/bash<br/>
if [ "${PAM_TYPE}" = "open_session" ]; then<br/>
echo -en "\u26A0\uFE0F SSH login: ${PAM_USER} from ${PAM_RHOST}" | curl -T- ntfy.sh/alerts<br/>
fi
</code>
<h3 id="example-collect-data" class="anchor">Example: Collect data from multiple machines</h3>
<p>
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:
</p>
<code>
while read result; do<br/>
[ -n "$result" ] && echo "result" >> results.csv<br/>
done < <(stdbuf -i0 -o0 curl -s ntfy.sh/results/raw)
</code>
2021-11-18 02:50:47 +01:00
<h2 id="faq" class="anchor">FAQ</h2>
2021-10-25 04:08:06 +02:00
<p>
2021-11-18 02:50:47 +01:00
<b id="isnt-this-like" class="anchor">Isn't this like ...?</b><br/>
2021-10-25 04:08:06 +02:00
Who knows. I didn't do a lot of research before making this. It was fun making it.
</p>
<p>
2021-11-18 02:50:47 +01:00
<b id="is-it-free" class="anchor">Can I use this in my app? Will it stay free?</b><br/>
2021-10-25 04:08:06 +02:00
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.
</p>
<p>
2021-11-18 02:50:47 +01:00
<b id="uptime-guarantees" class="anchor">What are the uptime guarantees?</b><br/>
2021-10-25 04:08:06 +02:00
Best effort.
</p>
<p>
2021-11-18 02:50:47 +01:00
<b id="multiple-subscribers" class="anchor">What happens if there are multiple subscribers to the same topic?</b><br/>
As per usual with pub-sub, all subscribers receive notifications if they are
subscribed to a topic.
</p>
<p>
<b id="can-you-spy-on-me" class="anchor">Will you know what topics exist, can you spy on me?</b><br/>
2021-10-25 04:08:06 +02:00
If you don't trust me or your messages are sensitive, run your own server. It's <a href="https://github.com/binwiederhier/ntfy">open source</a>.
2021-11-18 02:50:47 +01:00
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.
2021-10-25 04:08:06 +02:00
</p>
2021-11-18 15:22:33 +01:00
<p>
<b id="selfhosted" class="anchor">Can I self-host it?</b><br/>
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 <a href="https://github.com/binwiederhier/ntfy#installation">install instructions</a>
on GitHub.
</p>
2021-11-01 21:39:40 +01:00
<p>
2021-11-18 02:50:47 +01:00
<b id="why-firebase" class="anchor">Why is Firebase used?</b><br/>
2021-11-01 21:39:40 +01:00
In addition to caching messages locally and delivering them to long-polling subscribers, all messages are also
published to Firebase Cloud Messaging (FCM) (if <tt>FirebaseKeyFile</tt> is set, which it is on ntfy.sh). This
2021-11-18 02:50:47 +01:00
is to facilitate instant notifications on Android.
2021-11-01 21:39:40 +01:00
</p>
2021-11-18 15:22:33 +01:00
<p>
<b id="why-no-ios" class="anchor">Why is there no iOS app (yet)?</b><br/>
I don't have an iPhone or a Mac, so I didn't make an iOS app yet. I'd be awesome if
<a href="https://github.com/binwiederhier/ntfy/issues/4">someone else could help out</a>.
</p>
<h2 id="privacy" class="anchor">Privacy policy</h2>
2021-11-01 21:39:40 +01:00
<p>
Neither the server nor the app record any personal information, or share any of the messages and topics with
2021-11-03 16:33:34 +01:00
any outside service. All data is exclusively used to make the service function properly. The one exception
2021-11-01 21:39:40 +01:00
is the Firebase Cloud Messaging (FCM) service, which is required to provide instant Android notifications (see
FAQ for details).
</p>
<p>
The web server does not log or otherwise store request paths, remote IP addresses or even topics or messages,
2021-11-18 02:50:47 +01:00
aside from a short on-disk cache (for {{.CacheDuration}}) to support service restarts.
2021-11-01 21:39:40 +01:00
</p>
2021-10-25 04:08:06 +02:00
<center id="ironicCenterTagDontFreakOut"><i>Made with ❤️ by <a href="https://heckel.io">Philipp C. Heckel</a></i></center>
2021-10-24 03:29:45 +02:00
</div>
2021-11-08 15:24:34 +01:00
<div id="detail"{{if not .Topic}} style="display: none"{{end}}>
<div id="detailMain">
<button id="detailCloseButton"><img src="static/img/close_black_24dp.svg"/></button>
<h1><img src="static/img/ntfy.png" alt="ntfy"/><br/><span id="detailTitle"></span></h1>
<p class="smallMarginBottom">
<b>Ntfy</b> is a simple HTTP-based pub-sub notification service. This is a Ntfy topic.
To send notifications to it, simply PUT or POST to the topic URL. Here's an example using <tt>curl</tt>:
</p>
<code>
curl -d "Backup failed" <span id="detailTopicUrl"></span>
</code>
<p id="detailNotificationsDisallowed">
If you'd like to receive desktop notifications when new messages arrive on this topic, you have
<a href="#" onclick="return requestPermission()">grant the browser permission</a> to show notifications.
Click the link to do so.
</p>
<p class="smallMarginBottom">
<b>Recent notifications</b> (cached for {{.CacheDuration}}):
</p>
<p id="detailNoNotifications">
<i>You haven't received any notifications for this topic yet.</i>
</p>
<div id="detailEventsList"></div>
</div>
</div>
2021-11-09 16:46:47 +01:00
<div id="lightbox" class="lightbox"></div>
2021-10-24 20:22:53 +02:00
<script src="static/js/app.js"></script>
2021-10-23 03:26:01 +02:00
</body>
</html>
