Setup Guide

Download KumaAlert

Download KumaAlert from the App Store. The app requires iOS 17.0 or later.

Enter Your Server URL

You'll need the URL of your Uptime Kuma instance — the address you use to access your dashboard in a web browser (e.g., https://status.example.com). The app validates and tests the connection before proceeding.

Your server must be accessible from the internet — local network addresses won't work from your phone when you're away from home.

Sign In

Enter your username and password — the same credentials you use to log into your Uptime Kuma dashboard. If your server uses two-factor authentication (2FA), you'll be prompted for your TOTP code.

If your server has authentication disabled, the app detects this automatically and skips the credentials step.

Pin Your Favorites

Choose which monitors to pin for quick access on the Overview tab. You can select all, pick individual ones, or skip and change this later.

Choose Alert Types

Select which events you want push notifications for: monitors going down, services recovering, maintenance windows starting/ending, and flapping monitors.

You're Ready

The app shows a summary of your connected monitors and you're good to go. You can add home-screen widgets from here too.

API Key (Optional)

For background status checks when the app isn't open, add an API key. In your Uptime Kuma dashboard, go to Settings > API Keys and create a new key. Then in KumaAlert, go to Settings > your server and paste the key.

Cloudflare Access (Optional)

If your Uptime Kuma instance is behind Cloudflare Access, you'll need a Service Token:

1. Go to the Cloudflare Zero Trust dashboard
2. Navigate to Access > Service Auth > Service Tokens
3. Click Create a Service Token and copy the Client ID and Client Secret
4. In KumaAlert, go to Settings > your server > Cloudflare Access
5. Enable the toggle, enter the Client ID and Client Secret, then save

Custom HTTP Headers (Optional)

If your server sits behind a reverse proxy or custom authentication gateway, you can add arbitrary HTTP headers. Go to Settings > your server and add key-value pairs under Custom Headers.

Enable Notifications in KumaAlert

In KumaAlert, go to Settings > Notifications > Enable Push Notifications. The app will ask for permission to send notifications — tap Allow. Once enabled, you'll see a webhook URL appear on the screen.

Copy the Webhook URL

Tap Copy URL to copy the webhook URL to your clipboard. This is a unique URL that connects your Uptime Kuma server to your device. It looks something like:
https://push.kumaalert.app/webhook?relayId=abc123&secret=xyz789

Add a Notification in Uptime Kuma

Open your Uptime Kuma dashboard in a web browser and follow these steps:

1. Go to Settings > Notifications
2. Click Setup Notification
3. Set Notification Type to Webhook
4. Give it a name (e.g., "KumaAlert Push")
5. Set Post URL to the webhook URL you copied
6. Set Request Body to application/json
7. Leave the body content as the default — Uptime Kuma will send the monitor and heartbeat data automatically
8. Click Test to verify — you should receive a test notification on your phone
9. Click Save

Apply to Monitors

The notification can be applied to all monitors at once, or individually per monitor:

• All monitors: When creating the notification, check "Apply to all existing monitors" and "Auto apply for new monitors"
• Individual monitors: Edit a monitor, scroll to the Notifications section, and toggle on your KumaAlert notification

Set Up Quiet Hours (Optional)

Don't want alerts at 3am? In KumaAlert, go to Settings > Notifications > Quiet Hours. Set a start and end time — alerts during this window are held and delivered as a summary when quiet hours end.

You're All Set

You'll now receive push notifications whenever a monitor goes down or recovers. Notifications include the monitor name, status, and any error messages from the failed check.

If notifications stop working, go to Settings > Notifications in KumaAlert and tap Re-register Push Notifications. This generates a new webhook URL — you'll need to update it in Uptime Kuma.