Integrating Uptime Kuma with Home Assistant: Automated Downtime Alerting

Home Assistant is very good at reacting to things a door opens, a sensor trips, a time of day arrives. It’s less good, out of the box, at continuously polling whether your Nextcloud instance, your reverse proxy, or your Pi-hole is actually responding. That’s a job Uptime Kuma already does well. This guide connects the two: Uptime Kuma does the watching, Home Assistant does the deciding routing alerts based on time of day, who’s home, how urgent the service is, and whatever other context your automations already know.

Assumptions going in: you have a working Home Assistant instance and understand automations and integrations conceptually. You do not need prior Uptime Kuma experience that’s covered from install. If Uptime Kuma is already running somewhere on your network, you can skip to Integration Configuration. Version notes are called out inline where a specific Uptime Kuma or Home Assistant version matters.

Core Setup: Installing Uptime Kuma

If you’re running Home Assistant OS or Supervised, the simplest path is the community add-on:

1. In Home Assistant, go to Settings → Add-ons → Add-on Store
2. Click the three-dot menu → Repositories, add: https://github.com/hassio-addons/repository
3. Find Uptime Kuma in the store, click Install
4. Start the add-on, then open its Web UI from the add-on page

If you’re running Home Assistant Container, Core, or you’d rather keep Uptime Kuma fully independent of your Home Assistant instance (recommended if you want monitoring to survive a Home Assistant outage — more on that trade-off below), run it as a standalone Docker container instead:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    volumes:
      - ./data:/app/data
    ports:
      - 3001:3001
    restart: always

docker compose up -d

Either path gets you to the same setup wizard on first visit create your admin account, and you’re ready to add monitors.

Defining what to monitor

Add a monitor for each service you want Home Assistant to know about. In Uptime Kuma: Add New Monitor, pick a type, point it at the target:

Service type	Monitor Type	Example target
A web app or dashboard	HTTP(s)	https://nextcloud.yourdomain.com
Home Assistant itself	HTTP(s)	http://homeassistant.local:8123
A device with no web UI	Ping	Its IP address
A database or non-HTTP service	TCP Port	IP + port
DNS server (e.g. Pi-hole)	DNS	Hostname to resolve against it

Set the Heartbeat Interval to 60 seconds for most home services — there’s rarely a reason to check more frequently than that for the kind of alerting this guide sets up. <blockquote>

Design decision worth making now: should Uptime Kuma run on the same box as Home Assistant, or separately? If it runs alongside Home Assistant and Home Assistant goes down, your monitoring goes down with it including, ironically, the “is Home Assistant itself up” monitor. Running Uptime Kuma on separate hardware (a different VM, a Raspberry Pi, any always-on box) means it can actually alert you when Home Assistant is the thing that’s down. This matters more the more you rely on Home Assistant for actual notification delivery, which is exactly what this guide sets up so it’s worth deciding deliberately rather than defaulting to convenience. </blockquote>

Integration Configuration: Connecting the Two

There isn’t one single way to wire Uptime Kuma into Home Assistant there are three, and they solve different problems. Most setups end up using two of the three together.

Method 1: The official Home Assistant integration (pull — entities in HA)

Home Assistant ships a built-in Uptime Kuma integration that polls your Uptime Kuma instance and exposes each monitor as entities inside Home Assistant a binary_sensor (up/down state) and a sensor (additional detail) per monitor. This is the right method when you want monitor status visible on dashboards and usable as a trigger condition in the normal Home Assistant entity/state way, not just as a one-off push alert.

Setup:

1. In Uptime Kuma: Settings → API Keys → Add API Key. Give it a name, copy the generated key immediately (it’s shown once).
2. In Home Assistant: Settings → Devices & Services → Add Integration, search for Uptime Kuma.
3. Enter your Uptime Kuma instance’s URL (e.g. http://uptime-kuma.local:3001) and the API key from step 1.
4. Complete the setup Home Assistant creates one binary_sensor and one sensor entity per existing monitor automatically, and picks up new monitors you add later.

This method is a pull Home Assistant reaches out to Uptime Kuma on its own polling schedule. It won’t give you instant push notifications on its own, but it gives you clean, queryable entities to build automations, dashboards, and history graphs from.

Method 2: Uptime Kuma’s built-in Home Assistant notification (push — simplest)

Uptime Kuma has a dedicated Home Assistant notification type that calls Home Assistant’s own notify service directly when a monitor changes state no webhook automation required on the Home Assistant side.

Setup:

1. In Home Assistant, generate a Long-Lived Access Token: click your profile (bottom left) → scroll to Long-Lived Access Tokens → Create Token. Copy it immediately.
2. In Uptime Kuma: Settings → Notifications → Setup Notification, select Home Assistant as the type.
3. Fill in your Home Assistant URL, the access token from step 1, and the notify service you want it to call (e.g. mobile_app_your_phone_name find your exact service name under Developer Tools → Actions, searching for notify.).
4. Click Test, confirm the notification arrives on the target device.

This is the fastest path to a working push alert, but the payload is a plain message string you don’t get structured, template-able data the way you do with the webhook method below.

Method 3: Generic webhook (push — most flexible)

This is the method to reach for when you want to build custom logic around what the alert says, when it fires, and what else happens (flash a light, announce over a speaker, log to a database) rather than just deliver a plain notification.

Setup:

1. In Home Assistant, create a new automation with a Webhook trigger. Give it a memorable webhook ID, e.g. uptime_kuma_alert.
2. Home Assistant generates a URL in the form: https://your-ha-url/api/webhook/uptime_kuma_alert
3. In Uptime Kuma: Settings → Notifications → Setup Notification, select Webhook as the type.
4. Paste the URL from step 2 into Post URL, set Content Type to JSON.
5. Click Test — Home Assistant should log a webhook trigger event (check Settings → Automations → [your automation] → Traces to confirm it fired).

Uptime Kuma’s webhook payload includes a heartbeat object (status, message, ping time), a monitor object (name, type, target URL), and a top-level msg summary string — everything you need to build a detailed, templated alert message, which is exactly what the example automations below do. <blockquote>

If your Home Assistant instance sits behind Cloudflare Zero Trust, Authelia, or similar auth-gated access, the plain webhook URL likely won’t authenticate correctly from Uptime Kuma’s outbound request. Add the required auth header (a Cloudflare Service Token, for example) under the webhook notification’s Additional Headers field in Uptime Kuma the webhook method supports custom headers, which the built-in Home Assistant notification type (Method 2) does not, making Method 3 the better choice for anything sitting behind a reverse-auth layer. </blockquote>

Alert Configuration and Example Automations

Example 1: Alert when a service goes down

This automation uses the webhook method (Method 3), parses the incoming JSON, and only fires for actual down events filtering out the “up” events Uptime Kuma also sends through the same webhook.

alias: "Uptime Kuma - Service Down Alert"
description: "Notify when a monitored service goes down"
trigger:
  - platform: webhook
    webhook_id: uptime_kuma_alert
    allowed_methods:
      - POST
    local_only: false
condition:
  - condition: template
    value_template: "{{ trigger.json.heartbeat.status == 0 }}"
action:
  - service: notify.mobile_app_your_phone_name
    data:
      title: "🔴 Service Down"
      message: >
        {{ trigger.json.monitor.name }} is down.
        {{ trigger.json.heartbeat.msg }}
      data:
        priority: high
        tag: "uptime-kuma-{{ trigger.json.monitor.name }}"
mode: queued

The tag field is worth calling out on Android/iOS, setting a consistent tag per monitor means a later notification for the same monitor replaces the previous one on the lock screen instead of stacking duplicates, which matters if a service flaps.

Example 2: Alert when a service recovers

Same trigger, opposite condition — and a friendlier tone, since a recovery notification isn’t an emergency:

alias: "Uptime Kuma - Service Recovered"
description: "Notify when a monitored service comes back online"
trigger:
  - platform: webhook
    webhook_id: uptime_kuma_alert
    allowed_methods:
      - POST
    local_only: false
condition:
  - condition: template
    value_template: "{{ trigger.json.heartbeat.status == 1 and trigger.json.heartbeat.important == true }}"
action:
  - service: notify.mobile_app_your_phone_name
    data:
      title: "✅ Service Recovered"
      message: >
        {{ trigger.json.monitor.name }} is back up.
        Downtime resolved.
      data:
        tag: "uptime-kuma-{{ trigger.json.monitor.name }}"
mode: queued

The heartbeat.important flag in the payload is set on state-change events specifically (as opposed to every routine successful check), which is what keeps this automation from firing on every single healthy heartbeat without that condition, you’d get a “recovered” notification every 60 seconds for a service that was never actually down.

Example 3: State-based automation using the official integration’s entities

If you set up Method 1 alongside the webhook method, you can also trigger off the entity state directly useful for anything that isn’t a notification, like flashing a smart light red when a monitor drops:

alias: "Uptime Kuma - Flash Light on Outage"
trigger:
  - platform: state
    entity_id: binary_sensor.nextcloud_status
    to: "off"
    for:
      minutes: 2
action:
  - service: light.turn_on
    target:
      entity_id: light.office_lamp
    data:
      color_name: red
      flash: long

The for: minutes: 2 here is doing real work — see the false-positive section below for why.

Avoiding false positives and notification fatigue

A monitoring setup that cries wolf trains you to ignore it, which defeats the entire purpose. A few concrete patterns:

• Set Retries in Uptime Kuma itself, not just in Home Assistant. Under each monitor’s settings, Retries (2–3 is a sane default) means Uptime Kuma only marks something “down” and only fires the notification after multiple consecutive failed checks, absorbing brief network blips before they ever reach Home Assistant at all. This is the first and most effective place to reduce noise, upstream of anything Home Assistant does.
• Use for: duration on state-trigger automations (Example 3 above) as a second layer if you’re building entity-based automations this protects against the case where the entity flips state briefly even though Uptime Kuma’s own retry logic already filtered most of that out.
• Use the important flag (Example 2) to distinguish real state-change events from routine heartbeats when working with the raw webhook payload this is the single most common mistake in hand-rolled Uptime Kuma webhook automations, and it’s why the “recovered” example above explicitly checks for it.
• Set mode: queued on your alert automations rather than leaving the default (single), so a rapid sequence of events (multiple services going down at once during a real network outage) queues and delivers each notification in order instead of the automation silently dropping triggers that arrive while it’s already running.
• Route by severity, not just by service. A monitor for your production reverse proxy probably deserves an immediate, loud push notification. A monitor for a hobby project VM probably doesn’t need to wake you up. Use separate webhook automations (or a template condition checking trigger.json.monitor.name against a list) to route different monitors to different urgency levels a quiet log entry for low-priority services, a high-priority push with sound for anything that actually matters.

Uptime Kuma vs. Native Home Assistant Monitoring

Home Assistant can already do basic uptime checking on its own, without Uptime Kuma at all a rest binary sensor pointed at a URL, or a ping integration entity, or a command_line sensor running curl. It’s fair to ask whether adding a whole second service is worth it.

	Native HA sensors (REST/ping/template)	Uptime Kuma
Setup	YAML in configuration.yaml, or the config-flow UI for rest/ping	Web UI, no YAML required
Monitor types	HTTP status/content, ping, TCP (via command_line workarounds)	HTTP(s), keyword match, TCP, DNS, ping, Docker container state, SSL cert expiry, and more
Availability if Home Assistant is down	None — the checker and the alerting are the same process	Independent, if run on separate infrastructure — can alert on a Home Assistant outage itself
Retry/threshold logic to avoid flapping	Manual, via automation for: conditions you build yourself	Built in, per-monitor, no automation logic required
Historical uptime %, response time graphs	Not built in — requires the Recorder/History integration and manual dashboard building	Built in, per monitor, out of the box
Notification channels	Whatever Home Assistant’s notify platforms support	90+ built-in providers, independent of Home Assistant entirely
Best fit	A single quick check you want as a native entity with no extra infrastructure	Any real monitoring surface — more than a couple of services, or anything where you want the check to survive a Home Assistant outage

The honest trade-off: native Home Assistant sensors are simpler for a single check and keep everything in one place. But that single place is also a single point of failure if Home Assistant crashes, both your monitoring and your alerting for that monitoring go down together, silently. Uptime Kuma run independently avoids that specific failure mode, and adds retry logic, historical graphs, and a much wider monitor-type and notification-channel library without you having to hand-build any of it in YAML.

The architecture pattern that gets the best of both: let Uptime Kuma be the independent, resilient prober it doesn’t care whether Home Assistant is up, it just watches your services and can alert through its own channels (Discord, Telegram, Gotify) as a fallback even if the Home Assistant integration path fails entirely. Then layer Home Assistant on top via the webhook and/or official integration methods above specifically for the context-aware routing Home Assistant is good at that Uptime Kuma alone isn’t — don’t page my phone if I’m already looking at a wall-mounted dashboard showing the same alert, only flash the light red after dark, escalate to a phone call automation if a critical monitor stays down for more than 10 minutes. Uptime Kuma provides the raw, reliable signal; Home Assistant decides what to do with it based on everything else it already knows about your house and your presence.

Troubleshooting

Verifying the connection is actually working

For the official integration (Method 1): check Settings → Devices & Services → Uptime Kuma — if it shows entities with real (not “unavailable”) states, the API connection is working. An “unavailable” state usually means Home Assistant can’t reach the Uptime Kuma URL verify from the Home Assistant host itself with curl http://uptime-kuma-ip:3001 to rule out a network path issue before assuming the integration is misconfigured.

For the webhook method (Method 3): the cleanest test skips Uptime Kuma entirely and confirms Home Assistant’s side works in isolation:

curl -X POST https://your-ha-url/api/webhook/uptime_kuma_alert \
  -H "Content-Type: application/json" \
  -d '{"heartbeat":{"status":0,"msg":"test"},"monitor":{"name":"Test Monitor"}}'

If your automation fires from this manual curl, the Home Assistant side is confirmed working and any remaining issue is on Uptime Kuma’s end check its notification test button and logs next.

Common issues

Symptom	Likely cause	Fix
Webhook test in Uptime Kuma succeeds, but no notification arrives	Automation condition template doesn’t match the actual payload shape, or a typo in the webhook ID	Check Settings → Automations → [automation] → Traces in Home Assistant to see the exact payload received and where the condition evaluated false
Official integration shows monitors as “unavailable”	Network path blocked, wrong URL/port, or API key revoked	Confirm with curl from the HA host directly; regenerate the API key in Uptime Kuma if needed
Built-in Home Assistant notification type (Method 2) fails with an auth error	Long-lived access token expired or copied incorrectly	Generate a fresh token in your Home Assistant profile and re-enter it in the Uptime Kuma notification config
Notifications work when testing manually but not during a real outage	Retries/threshold set too high in Uptime Kuma, so the monitor hasn’t actually flipped to “down” yet by the time you’re checking	Lower Retries temporarily to 0 to confirm the pipeline fires quickly, then tune back up to a level that balances speed against false-positive tolerance
Duplicate notifications for the same outage	Both the webhook method and the built-in HA notification type configured simultaneously, each firing independently	Pick one push method per use case — use the webhook method for anything you want custom logic on, and don’t also enable Method 2 for the same monitor
Webhook works locally but not when Home Assistant is accessed remotely through a reverse proxy	Missing local_only: false in the trigger config, or the reverse proxy isn’t forwarding the request correctly	Confirm local_only: false is set (shown in the examples above) if Uptime Kuma and Home Assistant aren’t on the exact same local network path

Once the pipeline is working for one monitor, extending it to the rest is just adding monitors in Uptime Kuma the webhook and integration setup doesn’t need to be repeated per service. The architecture decision that matters most is the one from the top of this guide: where Uptime Kuma actually runs, and whether it can outlive a Home Assistant outage to tell you about one.