Skip to main content

Heartbeat Monitoring

Heartbeat monitoring is a passive approach: instead of PingZen checking your service, your service tells PingZen “I’m alive” by sending a simple HTTP request. If PingZen doesn’t receive a ping within the expected interval, it alerts you. For cron jobs, backups and scheduled scripts, see cron job monitoring.

What It Is For

Scheduled jobs

Database backups, log rotation, cleanup scripts, weekly reports and email campaigns. The job calls in after every run; if the call does not arrive in time and the grace period runs out, you get an alert.

Pipelines and background workers

ETL and data processing, queue consumers, deployment scripts and CI/CD. The start and success/fail signals show not just that the job ran, but how it ended; the job can report its run time itself in the duration_ms field.

startsuccessstartfail

Anything nothing can reach from the outside

A job on a laptop, inside a closed network or behind NAT — there is no address to poll. A heartbeat reverses the direction: instead of PingZen reaching the job, the job makes one outgoing HTTP request.

What It Is Not For

A heartbeat waits for your job to call in. When something is listening that you could poll instead, poll it:

You want to knowUse instead
Is my website or API up?HTTP monitor — it checks from the outside without you changing any code
Is a port open or a host reachable?TCP or Ping monitor
Why did the job fail?Out of scope — a heartbeat only knows that the call arrived, or did not

How It Works

  1. Create a heartbeat monitor in PingZen and get a unique ping URL
  2. Add an HTTP call to the end of your cron job, script, or pipeline
  3. PingZen expects to receive a ping within your configured interval
  4. If a ping is missed (plus grace period), PingZen sends an alert

Ping Signals

PingZen supports multiple signal types for granular job tracking:

Ping (GET)

Simple heartbeat — confirms the job ran

Start

Marks the beginning of a job run

Success

Marks successful completion

Fail

Reports a job failure and marks the monitor Down at once; error details can ride along as JSON, readable through the API

Integration Examples

Bash / Cron

# Add to the end of your cron job
curl -fsS --retry 3 https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG

Python

import requests
requests.get('https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG', timeout=10)

cURL with start/success signals

# Signal job start
curl -fsS -X POST https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/start

# ... your job runs ...

# Signal success
curl -fsS -X POST https://pingzen.dev/api/v1/ping/YOUR_PING_KEY/YOUR_SLUG/success

Key Features

  • Unique endpoint URL for each heartbeat monitor
  • Configurable intervals (1 minute to 30 days) — weekly and monthly cron jobs included
  • Grace period before alerting (1 minute to 24 hours)
  • Note for calendar-monthly jobs: after a 31-day month the gap lands exactly on the limit (30-day interval + 24-hour grace = 31 days), so any delay causes a false DOWN — schedule such jobs every 30 days instead
  • Start/success/fail signal tracking
  • Ping history is kept for 90 days — click any heartbeat to open its timeline and a log of the last 20 pings; JSON attached to a ping is available through the API
  • Optional secret check via the X-Secret header — switched on through the API or MCP
  • Pause/resume without losing configuration
  • Works with any language or tool that can make HTTP requests