📡 Uptime Kuma integration

Automatically open a Service Incident in Microscope whenever Uptime Kuma detects that a monitored service is down, using a Webhook notification authenticated with a Microscope API key.

How it works

When a monitor goes down, Uptime Kuma sends an HTTP POST to the Microscope incident endpoint with a custom JSON body. Microscope authenticates the call with an API key (sent as a header), resolves the caller's tenant from that key, and creates a new service incident attached to the workload you reference.

Uptime Kuma  ──POST /api/v1/tech/incidents (X-API-KEY)──▶  Microscope API  ──▶  Service Incident

Prerequisites

• A Microscope API key provisioned for your tenant (ask your administrator). The key carries the tenant and the role used to authorize the call.
• The Workload identifier the incident should be attached to (copy it from the workload page).
• The Microscope API base URL, e.g. https://your-microscope-host.

1. Create the Webhook notification in Uptime Kuma

In Uptime Kuma, go to Settings → Notifications → Setup Notification and choose Webhook.

Field	Value
Notification Type	Webhook
Post URL	https://your-microscope-host/api/v1/tech/incidents
Request Body	Custom Body

Custom Body

Paste the following JSON as the custom body. It uses Liquid templating, which Uptime Kuma renders before sending:

{
  "workloadId": "ef112e43-bc11-45c5-8c20-2515571fec39",
  "label": "{{ name }} availability incident",
  "incidentSeverity": 1
}

• workloadId — the Microscope workload the incident is attached to. Replace with your own id.
• label — {{ name }} is the Liquid variable for the monitor name, so a monitor named Web application produces the label Web application availability incident.
• incidentSeverity — the incident severity (see the table below).

💡 The startDate is optional. If you omit it (as above), Microscope sets it to the time the webhook is received. To use Uptime Kuma's exact detection time instead, add: "startDate": "{{ heartbeatJSON.time | replace: ' ', 'T' | append: 'Z' }}". Note that heartbeatJSON is only available on real UP/DOWN events, not on the Test button.

Severity values

Value	Severity
0	Low
1	Medium
2	High
3	Critical

Additional Headers

Uptime Kuma has no dedicated API-key field, so the key — and the content type — are passed as Additional Headers:

{
  "X-API-KEY": "dev-sample-key-002",
  "Content-Type": "application/json"
}

• X-API-KEY — your Microscope API key. Microscope reads it from this header, identifies the tenant, and authorizes the request.
• Content-Type: application/json — required. The endpoint only accepts JSON; without this header the request is rejected with HTTP 415 (Unsupported Media Type).

2. Assign the notification to your monitors

Creating the notification is not enough. Open each monitor you want to track, and in the Notifications section enable the webhook notification.

⚠️ The Test button works without this step, but real down-events only trigger the webhook for monitors that have the notification enabled.

Troubleshooting

Symptom	Cause / Fix
HTTP 415	Content-Type: application/json is missing from Additional Headers.
HTTP 401	The X-API-KEY is missing or invalid.
HTTP 403	The key's role is not allowed to create incidents.
Test creates an incident with label Monitor Name not available …	Expected — on Test there is no monitor, so {{ name }} falls back to a placeholder. Real events use the actual monitor name.
Monitor is down but no incident is created	The notification is not enabled on the monitor, or it has not yet exhausted its retry count. Check the monitor's Notifications and Retries settings.

ℹ️ Each down-event creates a new incident; Uptime Kuma does not deduplicate. If a service stays down across several heartbeats you may receive multiple incidents.