# How the Uptime Kuma Push Monitor Type Works for External Check-Ins

> Learn how Uptime Kuma push monitors allow external services to self-report health status via HTTP GET requests for passive monitoring. Features custom messages and latency tracking.

- Repository: [Louis Lam/uptime-kuma](https://github.com/louislam/uptime-kuma)
- Tags: internals
- Published: 2026-02-28

---

**The Uptime Kuma push monitor type enables external services to report their own health status via HTTP GET requests to a unique token-protected endpoint, creating passive monitoring without polling while supporting custom status messages and latency metrics.**

The push monitor type in Uptime Kuma provides a **passive monitoring** mechanism that inverts the traditional polling model. Instead of Uptime Kuma actively probing your services, your services push health data to the monitoring instance using a secure URL. This architecture, implemented in the `louislam/uptime-kuma` repository, is ideal for services behind firewalls, ephemeral CI/CD jobs, or environments where inbound access is restricted.

## Architecture of the Push Monitor System

### Token Generation and URL Structure

When you create a monitor with `type: "push"`, the backend generates a cryptographically random **32-character push token** stored in the `pushToken` field of the `monitor` table. This occurs in [`server/model/monitor.js`](https://github.com/louislam/uptime-kuma/blob/main/server/model/monitor.js) where the model defines the `pushToken` property.

The frontend constructs the check-in URL through computed properties in two Vue components:

- [`src/pages/EditMonitor.vue`](https://github.com/louislam/uptime-kuma/blob/main/src/pages/EditMonitor.vue) (lines 68-70)
- [`src/pages/Details.vue`](https://github.com/louislam/uptime-kuma/blob/main/src/pages/Details.vue) (lines 576-580)

The resulting URL follows this pattern:

```text
<base-url>/api/push/<pushToken>?status=up&msg=OK&ping=123

```

### The API Endpoint Handler

All push requests route to `router.all("/api/push/:pushToken")` in [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/main/server/routers/api-router.js) (lines 47-146). This Express router handler validates tokens, parses query parameters, and orchestrates the heartbeat creation pipeline without requiring authentication headers, relying solely on the entropy of the push token for security.

## Step-by-Step Processing Flow for External Check-Ins

When an external service performs a GET request to the push URL, Uptime Kuma executes an eight-step validation and recording process:

### 1. Token Validation

The router queries the database using `R.findOne("monitor", " push_token = ? AND active = 1 ", [pushToken])`. If the token does not match an active monitor, the request fails immediately with HTTP 404.

### 2. Parameter Parsing

The system extracts three query parameters from the request:

- **`status`**: Accepts `"up"` (default) or `"down"`, mapping to internal `UP` and `DOWN` constants
- **`msg`**: Optional free-form message string (defaults to `"OK"`)
- **`ping`**: Optional response time in milliseconds, strictly validated to be between `0` and `100000000000` ms

### 3. Heartbeat Bean Creation

A new heartbeat record is instantiated via the bean pattern, populated with the monitor ID, current timestamp, parsed ping value, custom message, and the previous heartbeat's `downCount`. If prior heartbeats exist in the database, the system calculates the `duration` field representing the time elapsed since the last check-in.

### 4. Status Determination

If the monitor is currently under maintenance, the status is forced to `MAINTENANCE` regardless of the pushed status. Otherwise, the internal `determineStatus()` helper evaluates the final state based on the `status` parameter, the monitor's previous state, and its configured retry policy.

### 5. Uptime Calculation

The `UptimeCalculator` class updates the monitor's statistical graphs and aggregate uptime percentages using the new heartbeat data before database persistence.

### 6. Database Persistence

The heartbeat bean's `end_time` is set to the current timestamp, and the complete record is saved to the database via the `heartbeat` table.

### 7. Real-Time Broadcasting

The system immediately emits the heartbeat to connected clients via WebSocket using `io.to(monitor.user_id).emit("heartbeat", bean.toJSON())`. Aggregate statistics are refreshed and broadcast to ensure dashboard consistency.

### 8. Notification and Export Logic

If the heartbeat meets the criteria defined in `Monitor.isImportantForNotification()`, alert notifications are dispatched immediately through configured channels. For monitors already in a down state with a `resendInterval` configured, the system may resend notifications after the specified number of consecutive down beats. The heartbeat is optionally pushed to a Prometheus exporter before the router returns a JSON response.

## Implementing External Check-Ins

### cURL Example

The simplest implementation uses a standard HTTP client to push status data:

```bash
curl "https://uptime.kuma.example/api/push/AbCdEfGhIjKlMnOpQrStUvWxYz123456?status=up&msg=Backup%20completed&ping=420"

```

### Node.js TypeScript Implementation

For services built with Node.js, the repository provides reference implementations in [`extra/push-examples/typescript-fetch/index.ts`](https://github.com/louislam/uptime-kuma/blob/main/extra/push-examples/typescript-fetch/index.ts):

```typescript
const pushURL = "https://uptime.kuma.example/api/push/AbCdEfGhIjKlMnOpQrStUvWxYz123456?status=up&msg=OK&ping=";

const push = async () => {
    await fetch(pushURL);
};

push();
setInterval(push, 60000); // Push every 60 seconds

```

Similar examples exist for Python, Go, PowerShell, and Bash in the `extra/push-examples/` directory.

### Creating Push Monitors via API

To programmatically create a push monitor, POST to the internal API endpoint:

```json
{
  "type": "push",
  "name": "Database Backup Job",
  "interval": 3600,
  "maxretries": 3,
  "notificationIDList": [1, 2],
  "tags": ["production", "backup"]
}

```

The API response includes the generated `pushToken`, which you must extract to construct the check-in URL for your external scripts.

## Why Use Push Monitors?

- **No polling overhead** – Eliminates network traffic from Uptime Kuma to your services, reducing bandwidth and compute costs.
- **Firewall and NAT traversal** – Works for services without public IP addresses or inbound port access, as long as the service can reach the Uptime Kuma instance.
- **Rich telemetry** – The `ping` and `msg` parameters allow reporting custom metrics like job duration, queue depth, or specific error codes alongside binary up/down status.
- **CI/CD integration** – Ideal for ephemeral environments like GitHub Actions, GitLab CI, or Kubernetes CronJobs where the service exists only for the duration of the task.

## Summary

- The **push monitor type** uses a passive architecture where external services report health via HTTP GET requests to `api/push/:pushToken`.
- A **32-character random token** generated in [`server/model/monitor.js`](https://github.com/louislam/uptime-kuma/blob/main/server/model/monitor.js) secures the endpoint and maps requests to specific monitors.
- The **router in [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/main/server/routers/api-router.js)** handles validation, heartbeat creation, uptime calculation, WebSocket broadcasting, and notification triggers in a single request lifecycle.
- **Query parameters** `status`, `msg`, and `ping` provide flexible telemetry options with built-in validation ranges.
- **Example implementations** in `extra/push-examples/` demonstrate integration patterns for Bash, TypeScript, Python, and other languages.

## Frequently Asked Questions

### What happens if I use an invalid push token?

Uptime Kuma returns an HTTP 404 response with the JSON payload `{ ok: false, msg: "Monitor not found or not active" }`. The router queries the database for a matching active monitor using `R.findOne("monitor", " push_token = ? AND active = 1 ", [pushToken])` and rejects requests where no match exists.

### Can I use push monitors for services behind a corporate firewall?

Yes. The push monitor is specifically designed for this scenario. Since the communication is initiated by your service outbound to Uptime Kuma, no inbound firewall rules or NAT port forwarding are required on the monitored service's network.

### How does Uptime Kuma handle maintenance windows for push monitors?

If a monitor is under maintenance mode when a push request arrives, the system forces the heartbeat status to `MAINTENANCE` regardless of the `status` parameter sent in the request. This prevents false positive notifications while scheduled work is performed.

### What is the maximum valid value for the ping parameter?

The `ping` parameter accepts values between `0` and `100000000000` milliseconds (approximately 3.17 years). The router validates this range in [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/main/server/routers/api-router.js) and rejects out-of-bounds values to prevent database overflow or logic errors.