Uptime Kuma integration

Uptime Kuma push notifications

PushPiper puts Uptime Kuma down and up alerts on your phone, free for 10,000 messages a month. You set it up with Uptime Kuma's built-in Webhook notification and a Custom Body, on version 1.23 and later, 2.x included.

Before you start

Grab two keys from PushPiper. Sign in at pushpiper.com/app (free, no credit card), create an app called Uptime Kuma for its API token (APP_TOKEN), and copy your user key (USER_KEY) from the dashboard.

Set up the Webhook notification

Go to Settings > Notifications and click Set Up Notification.
Pick Webhook as the Notification Type and name it PushPiper.
Post URL: https://api.pushpiper.com/1/messages.json
Request Body: choose Custom Body and paste the body below.
Click Test, then Save, and switch the notification on for your monitors.

Custom Body

token=APP_TOKEN&user=USER_KEY&title={{ monitorJSON.name | default: "Uptime Kuma" | url_encode }}&message={{ msg | url_encode }}&priority={% if heartbeatJSON.status == 0 %}1{% else %}0{% endif %}&sound={% if heartbeatJSON.status == 0 %}siren{% else %}pushover{% endif -%}

That's a form-encoded body, the same format Pushover clients send. Uptime Kuma posts a custom body as application/x-www-form-urlencoded unless told otherwise, so you don't need extra headers. url_encode keeps quotes, ampersands and line breaks in error messages intact.

Down alerts go out at priority 1 with the siren sound, so they get through quiet hours. Recoveries arrive at normal priority with the default sound. The test message has no monitor, so its title falls back to Uptime Kuma.

Prefer a JSON body?

PushPiper reads JSON too. Use this Custom Body instead and turn on Additional Headers with the header below. Without it, Uptime Kuma labels the body as form data.

{
  "token": "APP_TOKEN",
  "user": "USER_KEY",
  "title": {{ monitorJSON.name | default: "Uptime Kuma" | json }},
  "message": {{ msg | json }},
  "priority": "{% if heartbeatJSON.status == 0 %}1{% else %}0{% endif %}",
  "sound": "{% if heartbeatJSON.status == 0 %}siren{% else %}pushover{% endif %}"
}

{"Content-Type": "application/json"}

The json filter turns each value into a properly quoted JSON string, even when an error message contains quotes or newlines.

What you can put in the template

Uptime Kuma renders the body with LiquidJS. These are the values you'll reach for most:

Variable	What it holds
`msg`	The full alert text, like `[Monitor name] [🔴 Down] reason`
`monitorJSON.name`	The monitor's name, not set for test messages
`heartbeatJSON.status`	`0` down, `1` up, `2` pending, `3` maintenance
`name`, `status`, `hostnameOrURL`	Shortcuts added in Uptime Kuma 2.x

Want an alarm that keeps ringing for one critical monitor? Give it its own notification and swap the priority part for priority={% if heartbeatJSON.status == 0 %}2{% else %}0{% endif %}&retry=60&expire=3600. Emergency alerts repeat until acknowledged, see emergency priority.

Limits and caveats

The Pushover type is out. It's hardwired to api.pushover.net.
Custom Body needs 1.23.0 or later. 1.23.16 is the last 1.x release, 2.5.5 the current stable one.
No attachments. A webhook body can't carry a screenshot.
Keys in plain sight. Uptime Kuma stores the body, token included, as plain text. Give it its own PushPiper app so you can rotate that token on its own.
Apprise works too. It ships in the official Docker image. Pick the Apprise notification type and use a PushPiper forms:// URL from the Apprise guide.

Sources

Questions and answers

Can I use Uptime Kuma's Pushover notification with PushPiper?

No. The Pushover provider always posts to api.pushover.net and has no setting for another server. Use the Webhook notification with the Custom Body on this page. It sends the same Pushover-style fields to PushPiper.

Which Uptime Kuma versions does this work on?

Any version with the Custom Body option, so 1.23.0 and later, 2.x included. We rendered both bodies with the template and HTTP libraries that ship with 1.23.16 and 2.5.5 and checked what arrived.

Do I need Additional Headers?

Only for the JSON body. Uptime Kuma sends a custom body as application/x-www-form-urlencoded unless you set a Content-Type header, which is exactly right for the form body.

Why does the test notification say Uptime Kuma?

The Test button sends a message without a monitor, so the template falls back to Uptime Kuma as the title. Real alerts use the monitor's name.