Sending ntfy Notifications From Home Assistant: Setup, Priorities and Actionable Alerts
Nadia Pell
November 20, 2026
You already use ntfy for server alerts, or you just set up your own instance, and now you want Home Assistant to push to the same app: the washing machine is done, the garage door has been open for ten minutes, the freezer is warming up. For a long time that meant hand-writing a REST call in YAML. Since Home Assistant 2025.5 there is an official ntfy integration that does the job through the UI, supports priorities, tags, attachments and action buttons, and can even bring ntfy messages back into Home Assistant as events. This guide walks through setting it up, sending useful notifications, and the few settings that decide whether alerts arrive on time.
The official ntfy integration versus a hand-built REST call
Before the integration existed, the usual approach was a rest_command or REST notify platform that posted JSON to the ntfy server. That still works and is worth knowing for edge cases, but the integration is now the better default for most setups. Per the Home Assistant ntfy documentation, it gives you:
- A notify entity per topic, usable with the standard
notify.send_messageaction. - An
ntfy.publishaction that exposes ntfy’s full feature set: title, priority, tags, click URL, attachments, action buttons, delays, email forwarding and more. ntfy.clearandntfy.deleteactions to mark a notification as read or remove it, using the sequence ID you assigned when publishing.- An event entity per topic that receives messages in real time, so a message published to ntfy from anywhere can trigger an automation.
- Account sensors for message, email, call and attachment usage and limits, refreshed every 15 minutes.
- An update entity for self-hosted servers running ntfy 2.17.0 or later, when you connect with an administrator account.
If you are still choosing a notification service at all, our comparison of ntfy, Pushover and Gotify covers the trade-offs, and Apprise versus ntfy explains when a multi-service library fits better.
Adding ntfy to Home Assistant step by step
The integration is configured from the UI. Go to Settings > Devices & services, choose Add integration and search for ntfy. The setup dialog asks for:
- Service URL. The default is
https://ntfy.sh. For your own server, enter its public or LAN URL, for examplehttps://ntfy.example.com. - Verify SSL certificate. Leave this on unless you are deliberately using a self-signed certificate on a LAN-only instance.
- Username and password, optional. These are needed for protected topics. According to the Home Assistant docs, Home Assistant uses them to generate an access token and then authenticates with that token, so your password is not sent with every message.
After the server is added, you add one or more topics. You can type an existing topic name, the same one you subscribed to in the ntfy app, or let Home Assistant generate a random topic name. Each topic gets an optional display name, and that name becomes the entity ID, so a topic named “home alerts” shows up as something like notify.home_alerts.
Topic filters appear here too, letting you restrict which incoming messages the event entity reacts to by priority, tags, exact title or exact message. They apply only to the event entity, not to what you send.
Locking topics down on your own server
On ntfy.sh, topics are public by default, and the Home Assistant docs point out that anyone who knows a topic name can read it unless you reserve it with an account. Pick long, hard-to-guess names and avoid putting sensitive details in messages.
On a self-hosted server, the ntfy configuration docs recommend setting auth-default-access: deny-all for a private instance and then granting access per user and topic. Create a dedicated user for Home Assistant with write access to the topics it publishes to, and read access to any topic you want its event entity to watch. If you have not set up the server yet, self-hosting ntfy with Docker Compose covers users, the reverse proxy and iPhone delivery in one place.
The smallest working notification
Once the topic exists, any automation can send to it with the generic notify action, following the example in the Home Assistant docs. Snippets here use YAML’s compact inline style, one top-level key per line; paste them into the YAML editor and Home Assistant reads them like the usual indented form:
action: notify.send_messagetarget: {entity_id: notify.home_alerts}data: {message: "The washing machine has finished."}
This is fine for plain text. As soon as you want a title, a priority or a button, switch to ntfy.publish, which takes the same notify entity as its target and adds ntfy’s own fields under data.

Priorities and tags that change how the phone behaves
ntfy priorities run from 1 to 5, and in the ntfy.publish action you pass them as an integer in the priority field, with 3 as the default. The ntfy publishing docs describe what each level does on Android:
- 5, max or urgent: long vibration bursts, default sound and a pop-over notification.
- 4, high: a long vibration burst, default sound and a pop-over.
- 3, default: short vibration and the default sound.
- 2, low: no sound or vibration; it shows up when you pull down the notification drawer.
- 1, min: no sound or vibration, filed under other notifications.
A useful pattern: 5 for a leak or smoke alarm, 4 for things that need action soon, and 2 for routine status messages.
Tags are a list of strings. Per the integration docs, tags that match emoji shortcodes, like warning or rotating_light, are rendered as emojis in front of the title, and other tags are shown below the message. They also make filtering easier later, since the event entity can match on tags.
A leak alert might look like this:
action: ntfy.publishtarget: {entity_id: notify.home_alerts}data: {title: "Water detected under the sink", message: "Kitchen leak sensor is wet.", priority: 5, tags: [warning, droplet], click: "https://ha.example.com/lovelace/kitchen"}
The click field sets the URL opened when you tap the notification body. Pointing it at the relevant Home Assistant dashboard saves you from hunting for the right view.
Action buttons, including a webhook back into Home Assistant
The actions field accepts up to three buttons. The integration supports the four types ntfy defines:
viewopens a URL or app. Fields:label,url, optionalclear.httpsends an HTTP request. Fields:label,url, optionalmethod(default POST),headers,bodyandclear.broadcastsends an Android broadcast intent, which apps like Tasker or Sleep as Android can listen for. The ntfy docs mark this as Android-only.copycopies a value to the clipboard. Per the ntfy release notes, it arrived in server 2.17.0 and Android app 1.23.0, and the ntfy docs say it shows in the web and Android apps but not in browser desktop notifications.
Setting clear: true dismisses the notification after the tap, which keeps a handled alert from lingering.
Wiring an http button to a Home Assistant webhook
The http button is what makes ntfy notifications actionable. The request is sent from the device where you tap the button, so you can aim it at a Home Assistant webhook trigger. First, create an automation with a webhook trigger:
triggers: [{trigger: webhook, webhook_id: "garage-close-7f2c91d4e8"}]actions: [{action: cover.close_cover, target: {entity_id: cover.garage_door}}]
Then send a notification whose button calls it:
action: ntfy.publishtarget: {entity_id: notify.home_alerts}data: {message: "The garage door has been open for 10 minutes.", priority: 4, actions: [{type: http, label: "Close garage", url: "http://homeassistant.local:8123/api/webhook/garage-close-7f2c91d4e8", method: "POST", clear: true}, {type: view, label: "Open camera", url: "https://ha.example.com/lovelace/garage"}]}
Three details from the Home Assistant webhook trigger documentation matter here:
- Webhooks have no authentication. Anyone who knows the ID can fire it, so treat the ID like a password: long, random and never copied from a blueprint or forum post.
local_onlydefaults to true. The webhook only accepts requests from your local network. That means the button above works when your phone is on home Wi-Fi or connected through a VPN, but not over mobile data. Settinglocal_only: falseaccepts requests from the internet, including through Home Assistant Cloud, at the cost of exposing the ID.- Avoid webhooks for safety-critical actions. The docs specifically warn against using them to unlock doors. Closing a garage door is a judgment call; opening one or disarming an alarm from a notification button is not something to wire this way.
If you need the button to pass data, the trigger exposes the request body as trigger.json for JSON bodies and trigger.data for form data, so one webhook can handle several choices.

Attaching camera snapshots and files
ntfy can show an image directly in the notification. The integration gives you two fields for this:
attachtakes a URL of an image or file that the ntfy server and phone can reach.attach_fileuploads content from Home Assistant itself: a local file, a camera snapshot, text-to-speech output or an image from a media source. You pass amedia_content_idandmedia_content_type, and you can setfilenameto control the extension.
A doorbell automation could send:
action: ntfy.publishtarget: {entity_id: notify.home_alerts}data: {title: "Someone is at the door", attach_file: {media_content_id: "media-source://camera/camera.front_door", media_content_type: "application/vnd.apple.mpegurl"}, filename: front-door.jpg, tags: [bellhop_bell]}
This mirrors the camera example in the ntfy.publish docs. Uploaded attachments count against server limits. On ntfy.sh, per the ntfy publishing docs, uploaded files are capped at 15 MB each and 100 MB total per visitor by default and expire after three hours, while external URL attachments are not subject to those limits. On your own server, the defaults are attachment-file-size-limit: 15M and attachment-total-size-limit: 5G, and you can change both.
Other fields worth knowing
delayschedules delivery between 10 seconds and three days ahead. Combined withsequence_id, it can build a dead man’s switch: schedule an alert for 24 hours from now, and each time the check-in succeeds, send a new one with the same sequence ID to push the alert back, or clear it.markdownturns on Markdown formatting in the message body.iconsets a JPEG or PNG icon shown beside the notification.emailforwards the notification to an email address.callplaces a phone call that reads the message aloud; per the docs, this requires an ntfy Pro plan and a verified phone number.
Receiving ntfy messages as Home Assistant events
The event entity works in the other direction. Anything that publishes to a subscribed topic, whether a backup script, a monitoring tool or another server, becomes an event in Home Assistant, with the full message in the entity’s attributes: title, message, priority, tags, links and attachments. You can trigger on it like any other entity. For example, an automation can flash a hallway light whenever a priority 5 message lands on your infrastructure topic, by using a numeric_state trigger on the event entity’s priority attribute with above: 4, which is the pattern the integration docs use. Topic filters set during setup narrow this further, so you can react only to messages carrying a specific tag.
ntfy.sh limits versus your own server
The public ntfy.sh service is a reasonable place to start, but it has limits. The Home Assistant docs summarize the request rate as a burst of 60 messages, then one message replenished every five seconds. Other limits depend on your account tier, which you can see under Account > Usage on ntfy.sh, and the integration’s sensors report the same figures inside Home Assistant. ntfy.sh’s paid plans currently list Supporter at $5 a month with 2,500 daily messages, Pro at $10 a month with 20,000, and Business at $20 a month with 50,000, each with more reserved topics, emails, calls and larger attachments.
A self-hosted server can raise or remove these limits and keeps message content on your hardware. The trade-off is that it becomes one more thing to keep running. If the same machine hosts Home Assistant, your monitoring and ntfy, a single failure can take out the alert path along with whatever it was meant to warn you about, a problem covered in ntfy on the same box as Uptime Kuma.
Making iPhone notifications arrive promptly
iOS restricts background activity, so the ntfy iPhone app cannot hold a connection open to your server the way the Android app can. The ntfy configuration docs explain the fix: set upstream-base-url: "https://ntfy.sh" in your server’s server.yml. Your server then forwards a poll request to ntfy.sh, which relays it through Apple’s push service so the app knows to fetch the message from your server. The message content itself stays on your instance. Without this setting, the docs warn that delivery can take hours depending on the phone’s state. An optional upstream-access-token is only needed if you hit ntfy.sh’s rate limits or the upstream requires authentication.
When the old REST approach still makes sense
A rest_command remains useful if you run a Home Assistant version older than 2025.5, or need to publish to a topic you do not want registered as an entity. ntfy accepts JSON when you POST to the server’s root URL, not the topic URL, with topic as a required field, and accepts an access token as Authorization: Bearer tk_.... Tokens are created on the server with ntfy token add, and the ntfy docs note that a token currently grants full access to its user, so give Home Assistant its own user. A minimal definition in configuration.yaml:
rest_command: {ntfy_alert: {url: "https://ntfy.example.com", method: POST, headers: {Authorization: !secret ntfy_bearer}, content_type: "application/json", payload: '{"topic": "home_alerts", "title": "{{ title }}", "message": "{{ message }}", "priority": 4}'}}
Here ntfy_bearer in secrets.yaml holds the full header value, including the word Bearer. You call it with action: rest_command.ntfy_alert and pass title and message as data. You lose the event entity and usage sensors, so for new setups the integration is simpler.