UptimeGridUptimeGrid
Guide

Push Monitors

Push (heartbeat) monitors flip the model: instead of UptimeGrid polling your service, your service pings UptimeGrid. If the expected ping doesn't arrive in time, the monitor goes DOWN — perfect for cron jobs, backups, queue workers, and other background tasks.

How It Works

Each push monitor has a unique, secret Push URL containing a random token. Your job sends a request to that URL every time it runs successfully. UptimeGrid records a heartbeat and keeps the monitor UP. If no ping arrives within the expected period plus a grace window, UptimeGrid marks it DOWN and triggers your alerts.

  • Expected period — how often you promise to ping (e.g. every 60s).
  • Grace — extra slack before a missed ping counts as down (e.g. 300s).
  • The monitor goes DOWN after period + grace seconds without a ping.

Finding Your Push URL

Create a monitor with type Push, then open the monitor's detail page. The Push URL panel shows the full URL with Copy and Regenerate buttons. It looks like this:

https://ingest.uptimegrid.net/api/v1/push/<your-token>

Reporting a Heartbeat

Send a GET, POST, or HEAD request to the Push URL — no headers or authentication needed, the token in the URL is the credential.

curl

curl -fsS https://ingest.uptimegrid.net/api/v1/push/<your-token>

In a cron job

# Run the backup, then ping only if it succeeded
0 2 * * *  /usr/local/bin/backup.sh && curl -fsS https://ingest.uptimegrid.net/api/v1/push/<your-token>

Attaching a message

Add an optional msg query parameter (or JSON body field) to record context with the heartbeat. It's truncated to 255 characters.

curl -fsS "https://ingest.uptimegrid.net/api/v1/push/<your-token>?msg=backup%20ok"

Python

import urllib.request
urllib.request.urlopen("https://ingest.uptimegrid.net/api/v1/push/<your-token>", timeout=10)

Node.js

await fetch("https://ingest.uptimegrid.net/api/v1/push/<your-token>");

Security Best Practices

  • Treat the Push URL as a secret. Anyone with the token can send heartbeats and keep the monitor falsely UP. Don't commit it to source control or paste it in public chats.
  • Prefer POST when sharing matters. Link unfurlers, email scanners, and browser prefetch may automatically GET a URL pasted into chat or email, creating a spurious heartbeat. POST isn't auto-fetched, so use it where accidental GETs are a concern.
  • Always use HTTPS so the token isn't exposed in transit.
  • Regenerate if leaked. Use the Regenerate button on the monitor detail page to issue a new token; the old URL stops working immediately, so update your job too.
  • Rate limits. Pings are limited per token and per source IP. A normal heartbeat cadence is well within these limits — they exist to absorb misconfigured loops and abuse.

Notes

  • Pings only register an UP heartbeat; DOWN is inferred from missed pings.
  • Pinging a paused monitor is ignored.
  • Uptime for push monitors is measured as the fraction of expected ping windows that received a heartbeat.