Uptime Kuma notifications to your iPhone

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.
• Uptime Kuma 1.23 or later, for Custom Body and Additional Headers.

How to set it up

1. 1

   Create a source

   In the dashboard, go to Sources and create a source, for example with the slug uptime-kuma. You see the ingest key exactly once, so copy it right away.

2. 2

   Set up the webhook

   In Uptime Kuma, open Settings, then Notifications, and add a new one. Choose Webhook, enter the URL and set Request Body to Custom Body.

   Notification Type: Webhook
   Post URL:          https://api.pagerdeck.com/v1/push
   Request Body:      Custom Body

3. 3

   Define the payload

   Uptime Kuma renders the Custom Body with Liquid. The json filter quotes the message safely, even if it contains quotes itself. truncate keeps the title under the 250 byte limit. A monitor that is back up arrives as info, an outage as error.

   {
     "title": {{ msg | truncate: 60 | json }},
     "body": {{ msg | json }},
     "severity": "{% if heartbeatJSON.status == 1 %}info{% else %}error{% endif %}",
     "tags": ["uptime-kuma"]
   }

4. 4

   Set the key as a header

   Enter the ingest key under Additional Headers. It belongs in the header and never in the URL, where it would show up in every access log.

   {
     "Authorization": "Bearer src_live_REPLACE_ME"
   }

5. 5

   Test and assign monitors

   Test makes Uptime Kuma send a sample message, which must appear in your history. Then assign the notification to the monitors that should reach you.

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 uptime-kuma to critical and repeats until you acknowledge. Use the slug of your own source.

{
  "enabled": true,
  "stop": false,
  "when": {
    "source": [
      "uptime-kuma"
    ],
    "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

• Uptime Kuma does not send a key for an incident. The message that a service is back up therefore arrives as a separate message with info and does not close the outage. Without a rule, info becomes a banner with no sound.
• Uptime Kuma's built in Pushover notification always calls api.pushover.net and cannot be pointed at PagerDeck. Use the webhook instead.
• Android devices do not get push today. On Android, you use the history in the browser.

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

Does this also work with Uptime Kuma 2.0?

Yes. Custom Body and Additional Headers exist since version 1.23, and the template only uses the variables msg and heartbeatJSON, which both versions support.

Can I make individual monitors quieter without touching Uptime Kuma?

Yes. Uptime Kuma puts the monitor name into the message. A rule in PagerDeck checks the title with a pattern like /jellyfin/i and sets the level to low or silent.

Do I need the iPhone app?

For push on your phone, yes. Without a paired device, PagerDeck still accepts the messages and shows them in the history in the dashboard.

Why not use Pushover or ntfy directly from Uptime Kuma?

Both work, and for a single system that is often enough. PagerDeck pays off when several systems send alerts and you want one place to decide what wakes you at night.

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.

• Push notifications via webhook and curl

  One HTTP request with JSON. No SDK, no library, and the all-clear does not cost you an alert.

• Grafana alerts to your iPhone with your own rules

  One webhook contact point is enough. Grafana sends its default format, PagerDeck reads the title, urgency and links itself, and your rules decide how loud it gets.

• PagerDeck or ntfy

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