Forward macOS notifications to ntfy

First: which direction do you need?

Searches for ntfy on macOS mean two opposite things, so it is worth being clear about which one this page covers.

• Receiving ntfy messages on a Mac. ntfy has no official native Mac app. The usual answers are the ntfy web app, which can show desktop notifications from a browser, and the ntfy command line, which can run a command for each message. NotiFerry does not do this.
• Sending what happens on a Mac to ntfy. This is the subject here: getting the alerts your Mac apps post into an ntfy topic, so your phone or anything else subscribed to it can receive them.

Scripts publish themselves; apps cannot

For anything you run yourself, ntfy needs no helper. A single curl at the end of a command publishes to your topic; the guide to sending a notification from Mac to iPhone has the patterns.

Applications are the gap. A video export, a backup, a download, or an AI client tells you it is done with a macOS notification and nothing else. Turning those into ntfy messages means reading Notification Center, which macOS does not expose through a public API. You can build that yourself against the undocumented database, and some people do. NotiFerry is the packaged version: a sandboxed menu-bar app that watches Notification Center with read-only access to one folder and publishes each new entry to your topic.

What NotiFerry publishes

Each forwarded notification is one standard ntfy publish request in JSON. With the full-notification privacy mode it looks like this:

POST https://ntfy.sh/
Content-Type: application/json

{
  "topic": "nf-…",
  "title": "<source app> — <notification title>",
  "message": "<subtitle and body>",
  "priority": 3,
  "tags": ["computer"]
}

• Title is the source app, as macOS records it, followed by the notification title.
• Message is the subtitle and body. In the default title-only mode, and in generic mode, the message is replaced by “New notification” before anything leaves the Mac.
• Priority and tag are fixed at the default priority and the computer tag.
• Not included: icons, images and attachments, action buttons, click URLs, and the original sound.

Long titles and bodies are truncated to stay within ntfy's message size limit.

Server, authentication, and topic

NotiFerry uses the public https://ntfy.sh server by default and generates a topic for you: the prefix nf- followed by 60 random hexadecimal characters. You can rotate it at any time or replace it with a topic of your own.

In Settings, under Connection, you can point NotiFerry at your own ntfy server instead. Three things to know:

• The server URL must use HTTPS.
• Authentication can be none, an access token, or a username and password. Credentials are stored in the macOS Keychain.
• After you change the server, topic, or credentials, forwarding pauses until you confirm a new phone test.

Pacing, limits, and retries

• On ntfy.sh, NotiFerry sends about twelve messages a minute so a burst of Mac notifications does not trip the public server's rate limits.
• ntfy.sh documents a limit of 250 messages a day for anonymous publishing. NotiFerry keeps a local count and warns you as you approach it. It is meant for a handful of meaningful alerts, not a log stream.
• If the server is unreachable, up to 1,000 privacy-filtered notifications wait in a local queue for up to 24 hours and are retried with increasing delays.
• Pausing forwarding discards what arrives during the pause. Nothing is replayed when you resume.

NotiFerry is built and tested for delivery to the ntfy iPhone app. It publishes ordinary ntfy messages, so other clients subscribed to the same topic receive them too, but those combinations are not tested or supported.