Home Assistant alerts to your iPhone, with rules

Prerequisites

• A PagerDeck account with at least one paired device, so alerts have somewhere to land.
• A source in the dashboard with its credentials, see the first step below.
• Home Assistant 2024.10 or later for the example syntax (triggers and actions).

How to set it up

1. 1

   Create a source

   Create a source with the slug home-assistant and copy the ingest key.

2. 2

   Store the key in secrets.yaml

   The key belongs in secrets.yaml, not in configuration.yaml, which often lives in a Git repository.

   pagerdeck_auth: "Bearer src_live_REPLACE_ME"

3. 3

   Create the rest_command

   tojson quotes every value correctly. If you do not pass an urgency, the command sends warning. Restart Home Assistant afterwards.

   rest_command:
     pagerdeck:
       url: "https://api.pagerdeck.com/v1/push"
       method: post
       content_type: "application/json"
       headers:
         Authorization: !secret pagerdeck_auth
       payload: >-
         {"title": {{ title | tojson }},
          "body": {{ (message | default('')) | tojson }},
          "severity": {{ (severity | default('warning')) | tojson }},
          "tags": ["home-assistant"]}

4. 4

   Trigger it from an automation

   The water leak sensor sends critical. Whether that breaks through the silent switch at night is decided by your rule in PagerDeck.

   automation:
     - alias: "Water leak in the basement"
       triggers:
         - trigger: state
           entity_id: binary_sensor.basement_leak
           to: "on"
       actions:
         - action: rest_command.pagerdeck
           data:
             title: "Water detected in the basement"
             message: "binary_sensor.basement_leak switched to on"
             severity: critical

Payload

PagerDeck reads these fields on POST /v1/push. Only title is required, unknown fields are ignored.

{
  "title": "Disk almost full on web-01",
  "body": "/ is 94% used",
  "severity": "error",
  "tags": [
    "prod",
    "disk"
  ],
  "dedup_key": "web-01:disk",
  "url": "https://status.example.com/web-01",
  "ttl": "30m"
}

title

Required, at most 250 bytes.

body

Body text, at most 8 KiB.

severity

info, warning, error or critical. Without it the source default applies.

tags

At most 20, 64 bytes each.

dedup_key

Keeps an incident together until it is resolved.

url

A link for the app, http and https only.

ttl

Delivery deadline and automatic resolve, for example 30m.

Test it

Send a test alert straight to the API after setting PAGERDECK_KEY to your key. If it shows up in the app under your source, key and source are right and any problem sits in the sender configuration.

curl -sS -X POST https://api.pagerdeck.com/v1/push \
  -H "Authorization: Bearer $PAGERDECK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"PagerDeck test","body":"If you read this, the key works.","severity":"warning"}'

What the rules do with it

The sender proposes an urgency, your rule chain decides the alert level. This rule raises errors from the source home-assistant to critical and repeats until you acknowledge. Use the slug of your own source.

{
  "enabled": true,
  "stop": false,
  "when": {
    "source": [
      "home-assistant"
    ],
    "severity_at_least": "error"
  },
  "then": {
    "level": "critical",
    "repeat": {
      "every": "5m",
      "until": "ack",
      "max": 6
    }
  }
}

Set the volume

By source, title pattern, tags and time of day you can set a level from silent to critical.

Repeat until acknowledged

A rule repeats an alert at a fixed interval until you acknowledge it.

Escalate

If nobody reacts, PagerDeck notifies another address after a deadline.

What you should know

• Home Assistant has its own push through the Companion app. If one system and one phone are enough for you, that is the shorter route. PagerDeck pays off when several systems send alerts or you want to manage quiet hours and escalation in one place.
• PagerDeck is a delivery service, not an alarm system. Fire and burglary need a certified, independent channel as well.
• Android devices do not get push today.

Troubleshooting

When the API answers with a status code, it usually names the cause already.

202

Accepted and stored. This is not an error, delivery follows.

400

The input is invalid, for example a title over 250 bytes or malformed JSON. The message field gives the reason.

401

The key is missing, unknown or expired. Check the Authorization: Bearer header and that the key was copied completely.

402

The account may not send. Nothing is wrong with the connection, check the plan and billing in the dashboard.

413

The request is larger than 64 KiB. Limit the amount per request.

429

Sent too fast or quota used up. The Retry-After header says when to continue.

Frequently asked questions

What happens if Home Assistant itself goes down?

Then it sends nothing, and PagerDeck does not notice, because it does not check for heartbeats. A push monitor in Uptime Kuma that Home Assistant calls regularly covers that.

Do I need Nabu Casa or remote access?

No. The request goes outbound from your instance to api.pagerdeck.com. Inbound access to Home Assistant is not needed.

Can I tell messages apart by room or device?

Yes. Add your own tags to the payload and check them in rules with tags.any. That way the window sensor is quieter than the water leak sensor.

Are critical alerts always delivered?

The critical level needs your permission on the device. Without it, the level falls back to high for that device, visible in the history and without losing an alert.

Read next

• Homelab alerts in one place, with rules for the night

  Uptime Kuma, Home Assistant, NAS and backups report to PagerDeck. You decide once what wakes you at night.

• PagerDeck for building services

  Cooling, access, standby power, lifts: fault messages reach whoever is on call, and they decide which of them rings at night.

• Uptime Kuma notifications to your iPhone

  Uptime Kuma reports an outage via webhook. PagerDeck uses your rules to decide whether your phone rings.

• PagerDeck or ntfy

  Both send push via HTTP. ntfy is an open pub-sub service, PagerDeck an alerting service with receiver side rules.