Skip to content

Ntfy

Upstream docs: https://docs.ntfy.sh/publish/

URL Format

ntfy://host/topic/?priority=priority&tags=tag1,tag2&title=title

URL Fields

  • Username - Auth username
    Default: empty
    URL part: ntfy://username:password@host/topic/
  • Password - Auth password
    Default: empty
    URL part: ntfy://username:password@host/topic/
  • Host - Server hostname and port
    Default: ntfy.sh
    URL part: ntfy://username:password@host/topic/
  • Topic - Target topic name (Required)
    URL part: ntfy://username:password@host/topic/

Query/Param Props

Props can be either supplied using the params argument, or through the URL using
?key=value&key=value etc.

  • Actions - Custom user action buttons for notifications, see https://docs.ntfy.sh/publish/#action-buttons
    Default: empty

  • Attach - URL of an attachment, see attach via URL
    Default: empty

  • Cache - Cache messages
    Default: ✔ yes

  • Click - Website opened when notification is clicked
    Default: empty

  • Delay - Timestamp or duration for delayed delivery, see https://docs.ntfy.sh/publish/#scheduled-delivery
    Default: empty
    Aliases: at, in

  • DisableTLS - Disable TLS entirely (force HTTP scheme)
    Default: ❌ no

  • DisableTLSVerification - Disable TLS certificate verification
    Default: ❌ no

  • Email - E-mail address for e-mail notifications
    Default: empty

  • Filename - File name of the attachment
    Default: empty

  • Firebase - Send to firebase
    Default: ✔ yes

  • Icon - URL to use as notification icon
    Default: empty

  • Priority - Message priority with 1=min, 3=default and 5=max
    Default: default
    Possible values: Min, Low, Default, High, Max

  • Scheme - Server protocol, http or https
    Default: https

  • Tags - List of tags that may or not map to emojis
    Default: empty

  • Title - Message title
    Default: empty

Getting Started

Ntfy supports both the public ntfy.sh service and self-hosted instances. For the public service, simply use ntfy.sh as the host. For self-hosted instances, specify your server's hostname and port.

Public ntfy.sh service

ntfy://ntfy.sh/mytopic

Self-hosted instance

ntfy://my-ntfy-server.com:8080/mytopic

Topics are user-defined and can be any string. For authentication, include username and password in the URL if your ntfy server requires it.

Features

Ntfy offers several advanced features that enhance notification capabilities:

  • Action Buttons: Add interactive buttons to notifications that can trigger HTTP requests, open URLs, or broadcast intents
  • Attachments: Send files and images as attachments via URL or direct upload
  • Delayed Delivery: Schedule notifications for future delivery using timestamps or duration strings
  • Email Notifications: Forward notifications to email addresses for additional reach
  • Priority Levels: Set message priority from 1 (min) to 5 (max) to control notification behavior
  • Tags and Emojis: Add tags that automatically map to emojis for visual enhancement
  • Click Actions: Specify URLs that open when notifications are tapped
  • Message Caching: Control whether messages are cached for offline delivery

For complete feature documentation, see the ntfy publish documentation.

Optional Parameters

Commonly used parameters can be added as query parameters to customize notifications:

  • priority: Message priority level (1-5, where 1=min, 3=default, 5=max)
  • title: Custom title for the notification
  • tags: Comma-separated list of tags (e.g., warning,alert maps to ⚠️🚨)
  • actions: JSON array of action buttons (see action buttons docs)
  • delay: Schedule delivery (e.g., 5m for 5 minutes, 2023-12-31T23:59:59Z for specific time)
  • email: Email address to send notification to
  • click: URL to open when notification is clicked

High-priority notification with tags

ntfy://ntfy.sh/alerts/?priority=5&tags=warning,fire&title=System+Alert

Note

Action buttons require JSON formatting. See the upstream documentation for detailed syntax.

TLS Configuration

Ntfy supports two TLS-related configuration options to handle different security scenarios:

  • DisableTLSVerification: When set to true, disables TLS certificate verification. This allows connections to servers with self-signed or invalid certificates, but still uses the HTTPS protocol. Use this option when you trust the server but the certificate cannot be verified by standard means.

  • DisableTLS: When set to true, disables TLS entirely and forces the use of the HTTP scheme instead of HTTPS. This makes the connection unencrypted and should only be used in secure, trusted environments or for testing purposes.

Warning

Using either of these options reduces the security of your connection. DisableTLS is particularly insecure as it transmits data in plain text. Only use these options when necessary and in controlled environments.

Examples

Basic notification

ntfy://ntfy.sh/mytopic

With authentication

ntfy://username:password@ntfy.sh/privatetopic

With parameters

ntfy://ntfy.sh/updates/?priority=4&tags=info,computer&title=Server+Update

Delayed notification

ntfy://ntfy.sh/reminders/?delay=1h&title=Meeting+in+1+hour

With action button

ntfy://ntfy.sh/tasks/?actions=[{"action":"view","label":"Open Dashboard","url":"https://dashboard.example.com"}]&title=Task+Completed