Ntfy
Ntfy is a PUB/SUB for sending/receiving push notifications. It uses simple HTTP requests, making it highly flexible and portable, and can be self-hosted easily with Docker.
TODO
- Break this file up into smaller sections
- Add example Bash scripts for controlling Dockerized ntfy instance
Quick How-To
Ntfy works off of HTTP requests. This makes it highly flexible, allowing you to choose which HTTP client you use. Throughout this page, code examples have a header with tabs indicating a language to show the example in, i.e. Command line (curl), ntfy CLI, HTTP, etc.
This section assumes you are using Bash + cURL. It should be easy to translate the examples if you’re using another tool or library. In cURL, -d is the “data” to send (i.e. the message), -H is a header, and -u is for API token auth.
An Ntfy request needs, at minimum, the data/message to send and a URL to your topic, i.e. ntfy.sh/topicName. If you are self-hosting ntfy, replace any ntfy.sh domain in this section with your domain, i.e. ntfy.example.com.
This page as a full list of supported parameters you can pass in a request.
Basic notification
This is a very simply request that sends a message “Hello, world!” to the greetings topic on Ntfy’s official PUBSUB instance.
curl -d "Hello, world!" ntfy.sh/greetingsTitle, priority, and tags
To set the title, priority, and tags properties, pass them as headers to cURL with -H "<key>: <value>". You can optionally pass them as X-<Key>.
Priorities range from 1 to 5, with 1 being the lowest and 5 being the highest priority.
curl \
-H "X-Title: This is a notification title" \
-H "X-Priority: urgent" \
-H "X-Tags: warning,skull" \
-d "This is an urgent alert!" \
ntfy.sh/urgent-alertsYou can do multi-line messages, too.
curl \
-H "X-Title: Multiple lines?" \
-d "This message will have multiple lines.
Just add newlines without closing the quote,
splitting the content over multiple lines."
ntfy.sh/multiple-linesStyle messages with emoji & tags
See the ntfy tags & emojis docs
You can pass an X-Tags parameter to add tags to a notification.
curl -H "X-Tags: warning,somehostname,job-name" \
-d "Job name failed on host: somehostname" \
ntfy.sh/backupsYou can also pass them with -H ta:tagname (no quotes).
Style messages with Markdown
ntfy docs: Markdown formatting
curl \
-H "X-Markdown: yes" \
-d "This message is *styled*! **Big and bold**.
> Let he who is without blame throw the first stone.
```python
print(f"This is a code block in a message!")
```
[This is a link to Ntfy](https://ntfy.sh)
Things to do:
- Make some requests of your own!
- Learn Ntfy syntax
- Pick a tool
- cURL
- Powershell Invoke-WebRequest
- Python httpx/requests
- Create some notifications!
---
That's all, folks."
ntfy.sh/markdown-messageAttachments
Ntfy attachments documentation
Action buttons
Ntfy action buttons documentation
Priorities
| Priority | ID | Name | Description |
|---|---|---|---|
| Max | 5 | max/urgent | Really long vibration bursts, default notification sound with a pop-over notification. |
| High | 4 | high | Long vibration burst, default notification sound with a pop-over notification. |
| Default | 3 | default | Short default vibration and sound. Default notification behavior. |
| Low | 2 | low | No vibration or sound. Notification will not visibly show up until notification drawer is pulled down. |
| Min | 1 | min | No vibration or sound. The notification will be under the fold in “Other notifications”. |
Examples:
curl -H "X-Priority: 5" -d "An urgent message" ntfy.sh/alerts
curl -H "Priority: low" -d "Low priority message" ntfy.sh/alerts
curl -H p:4 -d "A high priority message" ntfy.sh/alertsScheduled Messages
If message caching is enabled on the server, you can pass a header with syntax describing when the message should be sent. Header options are X-Delay, X-At, X-In.
Examples:
curl -H "At: tomorrow, 10am" -d "Good morning" ntfy.sh/hello
curl -H "In: 30min" -d "It's 30 minutes later now" ntfy.sh/reminder
curl -H "Delay: 1639194738" -d "Unix timestamps are awesome" ntfy.sh/itsaunixsystemSend as GET requests with webhooks
Publish as JSON
In some instances, you may not have control over the headers of a request, such as with Jellyfin. You can also pass your full notification as JSON. The example below uses most of thee available parameters. The only required parameter is topic.
curl ntfy.sh \
-d '{
"topic": "alerts",
"message": "Disk space is low at 5.1 GB",
"title": "Low disk space alert",
"tags": ["warning","cd"],
"priority": 4,
"attach": "https://filesrv.lan/space.jpg",
"filename": "diskspace.jpg",
"click": "https://homecamera.lan/xasds1h2xsSsa/",
"actions": [{ "action": "view", "label": "Admin panel", "url": "https://filesrv.lan/admin" }]
}'