Skip to content

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

Table of Contents

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/greetings

Title, 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-alerts

You 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-lines

Style 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/backups

You 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.

![meaning image tag name](url-to-file)

```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-message

Attachments

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/alerts

Scheduled Messages

Ntfy scheduled message docs

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/itsaunixsystem

Send as GET requests with webhooks

Ntfy webhooks docs

Publish as JSON

Ntfy JSON publishing docs

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" }]
  }'