Home Assistant push notifications

Before you start

You need two keys from PushPiper, both 30 characters long.

1. Sign in at pushpiper.com/app. It's free and needs no credit card.
2. Create an app called Home Assistant. Its API token is your APP_TOKEN.
3. Copy your user key from the dashboard. That's your USER_KEY.
4. Open PushPiper on your phone and allow notifications. On iPhone or iPad, add it to your Home Screen first (iOS 16.4 or later).

Send notifications with notify.rest

Put your keys in secrets.yaml and add a rest notify platform to configuration.yaml. Restart Home Assistant afterwards.

pushpiper_token: APP_TOKEN
pushpiper_user: USER_KEY

notify:
  - name: pushpiper
    platform: rest
    resource: https://api.pushpiper.com/1/messages.json
    method: POST
    title_param_name: title
    data:
      token: !secret pushpiper_token
      user: !secret pushpiper_user
      priority: "{{ data.priority | default(0) }}"

That gives you a notify.pushpiper action. method: POST sends a form-encoded body, the same format Pushover clients use. Everything under data: rides along with each message, and the priority line picks up an optional value per call.

action: notify.pushpiper
data:
  title: Front door
  message: The front door has been open for 10 minutes.
  data:
    priority: 1

No title? The notification says Home Assistant. No inner data:? It goes out at normal priority.

Sounds, links and emergencies with rest_command

notify.rest sends the same fields every time. For per-call sounds, links or an emergency alarm that keeps ringing, use rest_command. It builds the whole request body from a template, so each call can set its own sound, link and priority.

rest_command:
  pushpiper:
    url: https://api.pushpiper.com/1/messages.json
    method: post
    content_type: application/x-www-form-urlencoded
    payload: >-
      {%- set fields = {
        "token": "APP_TOKEN",
        "user": "USER_KEY",
        "title": title | default("Home Assistant"),
        "message": message,
        "priority": priority | default(0)
      } -%}
      {%- if sound is defined %}{% set fields = dict(fields, sound=sound) %}{% endif -%}
      {%- if url is defined %}{% set fields = dict(fields, url=url) %}{% endif -%}
      {%- if fields.priority | int == 2 -%}
        {%- set fields = dict(fields, retry=retry | default(60), expire=expire | default(3600)) -%}
      {%- endif -%}
      {{ fields | urlencode }}

action: rest_command.pushpiper
data:
  title: Smoke alarm
  message: Smoke detected in the hallway.
  priority: 2
  sound: siren

Priority 2 repeats the alert every retry seconds until someone acknowledges it, for up to expire seconds. The template defaults to 60 and 3600. The API needs retry of at least 30 and expire of at most 10800, see emergency priority.

!secret only works as a whole value, not inside a template, so the keys sit in the payload here. Sharing your config? Move the entire payload into secrets.yaml and write payload: !secret pushpiper_payload.

Priorities and sounds

There are 23 built-in sounds, like pushover (the default), cashregister and siren, plus vibrate and none. Pass one as sound to rest_command. The full list is in the sound reference.

Limits and caveats

• No Pushover integration. Its host is fixed in the library it uses, so it can't reach PushPiper. Use notify.rest or rest_command.
• No attachments. Neither notify.rest nor rest_command can upload a camera snapshot.
• Errors are quiet. A rejected request, like a wrong token (HTTP 400), doesn't stop the automation. notify.rest only writes it to the Home Assistant log; rest_command can hand you the status code through response_variable.
• Size limits. Messages up to 1,024 characters, titles up to 250.
• Reloading. Restart Home Assistant after editing the YAML, or use the rest.reload action for notify: changes and rest_command.reload for rest_command: changes.
• Free plan. 10,000 messages a month. Past that, the API answers HTTP 429 until your quota resets on the 1st.

Related guides

• Uptime Kuma: Down alerts at high priority with a siren, recoveries at normal priority, through the Webhook notification.
• n8n: One HTTP Request node, keys in a Custom Auth credential, any field from your workflow.
• Shell and cron: A curl one-liner, a reusable push script and cron recipes for failures and finished jobs.

Sources

• Home Assistant: RESTful Notifications
• Home Assistant: RESTful Command
• Home Assistant source: rest/notify.py
• Home Assistant source: Pushover config flow
• pushover_complete 1.2.0 on PyPI