Skip to content

Heartbeat Monitoring

Plan availability

Heartbeat monitoring requires a paid plan.

Receive pings from your cron jobs, scheduled tasks, and background processes. UptimeObserver alerts you when an expected ping doesn't arrive on time—so you know immediately if a critical job fails to run.


How Heartbeat Monitoring Works

Unlike other monitor types where UptimeObserver checks your endpoint, Heartbeat Monitoring reverses the flow: your system sends a ping to UptimeObserver at regular intervals.

  1. You create a Heartbeat monitor in UptimeObserver and get a unique heartbeat URL
  2. Your cron job, scheduled task, or script sends an HTTP request (GET, POST, or HEAD) to that URL each time it runs successfully
  3. UptimeObserver expects a ping within your configured interval. Once the interval and grace period pass, the overdue checks apply your retry setting and can mark the monitor DOWN, triggering your configured alerts

This is ideal for monitoring jobs that run on a schedule—backups, data pipelines, report generation, or any task where you want to know not just "is the server up" but "did the job actually run."

Heartbeat monitor creation form


Configuration Options

Name

Give your monitor a descriptive name that identifies the job or task:

  • Nightly Database Backup
  • Daily Invoice Generation
  • Hourly Data Sync

Heartbeat URL

Each monitor gets a unique URL. Your scripts or cron jobs must call this URL on every successful run:

https://uptimeobserver.com/ping/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Keep the URL Secret

Treat your heartbeat URL like a password. Anyone with the URL can send pings and keep the monitor healthy. If the URL is exposed, regenerate it from the monitor settings.

POST Payload (Optional)

When sending a POST request, you can include a JSON body with metadata about your job's execution:

{
  "success": true,
  "exitCode": 0,
  "durationMs": 1250,
  "message": "Backup completed successfully: 342 files, 1.2 GB",
  "timestamp": "2026-07-01T02:00:05Z"
}
Field Type Description
success Boolean Whether the job succeeded (true) or failed (false)
exitCode Integer Process exit code
durationMs Long Execution duration in milliseconds
message String Custom message or log summary
timestamp String ISO 8601 timestamp of when the job ran

All fields are optional — a simple POST without a body is treated the same as GET.

Failure metadata does not trigger a Down event

success and exitCode are stored in ping history; they do not determine monitor health. A POST with success: false still refreshes the expected-ping deadline. To detect a failed job, do not send a heartbeat for that run. UptimeObserver alerts when the expected ping is overdue, not immediately when the process exits.

Expected Interval (Period)

Configure how often you expect a ping to arrive:

Interval Use Case
1 minute Frequently running jobs
5 minutes Near-real-time task monitoring
15 minutes Routine scheduled tasks
30 minutes Periodic batch jobs
1 hour Hourly cron jobs
6 hours Jobs that run four times daily
12 hours Daily morning/evening jobs
24 hours Daily backup and maintenance tasks
Custom Any custom interval in minutes

Grace Period

The grace period defines how long UptimeObserver waits after the expected interval before marking the monitor as down:

  • Default: 0 seconds; set a buffer if late completion is acceptable
  • Short: 1-2 minutes for critical, frequent jobs
  • Long: 30-60 minutes for jobs where minor delays are acceptable

Example

If your interval is 1 hour with a 5 minute grace period, the next ping is expected within 1 hour and 5 minutes of the last successful ping. The monitor goes down only after that window passes with no ping received.

Overdue Checks and Retries

UptimeObserver checks for overdue heartbeats approximately every 30 seconds. With the default Retries = 0, the first check after the deadline generates Down. With Retries = N, Down is generated after N + 1 overdue checks; these are deadline checks, not extra requests to your job. A processed ping moves the deadline forward, and the next non-overdue check returns a Retry or Down monitor to Up and generates a Monitor Up event.

A new monitor stays Pending until its first ping is processed. Send an initial successful ping and verify the monitor is active; an unused Pending monitor does not detect missed runs.


Setting Up a Heartbeat in Your Cron Job

Linux/macOS (Cron)

Add a curl or wget call to your cron job:

# Run backup script and ping UptimeObserver on success
0 2 * * * /usr/local/bin/backup.sh && curl -fsS --retry 3 https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID

For POST metadata, save the following wrapper as /usr/local/bin/heartbeat-job.sh. It runs under /bin/sh, records the job's exit status immediately, and sends a ping only after success. It requires curl and date +%s (available on Linux and macOS); duration has one-second resolution and is reported in milliseconds.

#!/bin/sh

: "${HEARTBEAT_URL:?Set HEARTBEAT_URL to your private heartbeat URL}"
if [ "$#" -eq 0 ]; then
    printf 'Usage: heartbeat-job.sh command [arguments...]\n' >&2
    exit 64
fi

started_at=$(date +%s) || exit 1
if "$@"; then
    job_exit_code=0
else
    job_exit_code=$?
fi
if [ "$job_exit_code" -ne 0 ]; then
    printf 'Job failed with exit code %s; no heartbeat sent.\n' "$job_exit_code" >&2
    exit "$job_exit_code"
fi

finished_at=$(date +%s) || exit 1
duration_ms=$(( (finished_at - started_at) * 1000 ))
# Avoid a negative duration if the system clock moved backwards.
if [ "$duration_ms" -lt 0 ]; then
    duration_ms=0
fi
payload=$(printf '{"success":true,"exitCode":%d,"durationMs":%d}' \
    "$job_exit_code" "$duration_ms")

curl -fsS --connect-timeout 10 --max-time 30 --retry 3 \
    -H 'Content-Type: application/json' \
    --data "$payload" "$HEARTBEAT_URL"

Then add this to the job owner's crontab, replacing the URL and command:

HEARTBEAT_URL=https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID
0 2 * * * /bin/sh /usr/local/bin/heartbeat-job.sh /usr/local/bin/backup.sh

The URL must be available to cron; an environment variable set only in your interactive shell is not enough. Keep the crontab and wrapper private, or load the URL from a restricted configuration file. Use absolute paths for the job and its dependencies.

Verify the wrapper: run it with /bin/true and confirm a ping appears, then with /bin/false and confirm there is no new ping. A failed job returns its original nonzero exit code. After a successful job, a failed curl call returns curl's nonzero exit code; do not interpret it as a failed backup. A missing ping alerts only after the interval plus grace period.

# Or with wget
0 2 * * * /usr/local/bin/backup.sh && wget -qO- https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID

systemd Timer

Add the heartbeat ping to your service or timer script:

[Service]
Type=oneshot
ExecStart=/usr/local/bin/backup.sh
ExecStartPost=/usr/bin/curl -fsS https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID

Windows Task Scheduler

In your PowerShell or batch script:

# Run your job
.\backup.ps1

# Ping UptimeObserver on success
if ($?) {
    Invoke-RestMethod -Uri "https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID"
}

GitHub Actions

- name: Scheduled backup
  run: ./backup.sh

- name: Ping UptimeObserver
  if: success()
  run: curl -fsS https://uptimeobserver.com/ping/${{ secrets.HEARTBEAT_ID }}

Docker / Kubernetes (CronJob)

apiVersion: batch/v1
kind: CronJob
metadata:
  name: backup-job
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: my-backup-image
            command:
            - /bin/sh
            - -c
            - |
              /usr/local/bin/backup.sh && \
              curl -fsS https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID
          restartPolicy: OnFailure

Common Use Cases

Nightly Database Backups

Monitor that your backup script runs every night:

  • Interval: 24 hours
  • Grace Period: 30 minutes
  • Cron: 0 2 * * * pg_dump ... && curl ...

Data Pipeline / ETL Jobs

Ensure your data pipeline completes on schedule:

  • Interval: 1 hour
  • Grace Period: 15 minutes
  • Script: Data extraction > transformation > load > heartbeat ping

Certificate Renewal

Monitor your auto-renewal scripts (e.g., Let's Encrypt):

  • Interval: 12 hours
  • Grace Period: 1 hour
  • Cron: 0 */12 * * * certbot renew && curl ...

Report Generation

Get alerted if daily/weekly reports aren't generated:

  • Interval: 24 hours
  • Grace Period: 2 hours
  • Script: Generate report > email > heartbeat ping

Health Checks for Workers

Ensure background workers or queue processors are alive:

  • Interval: 5 minutes
  • Grace Period: 2 minutes
  • Script: Check worker status > heartbeat ping

IoT / Edge Device Connectivity

Verify that remote devices are phoning home:

  • Interval: 15 minutes
  • Grace Period: 10 minutes
  • Device: Send sensor data > heartbeat ping

When to Use Heartbeat Monitoring

Use Heartbeat When

  • You need to verify a scheduled task actually ran, not just that the server is up
  • Your job runs periodically (hourly, daily, weekly) rather than continuously
  • The task is push-based—your system initiates the work and you want to confirm completion
  • You need to monitor processes behind firewalls or NAT that can't be reached from the outside

Use Other Monitor Types When

  • You need to check that a service is continuously available (use HTTP, Port)
  • You need to verify response content or status codes (use HTTP)
  • You need to check DNS records (use DNS)
  • You need to check network reachability (use Ping)

Combine With Other Monitors

Heartbeat monitoring works best alongside other monitor types:

  • Use HTTP Monitoring for your web application's availability
  • Use Port Monitoring for your database server
  • Use Heartbeat Monitoring to ensure your nightly backup of that database actually runs

Security Considerations

Keep the Heartbeat URL Private

Protect Your URL

Anyone with the heartbeat URL can send a ping and prevent the monitor from alerting. If the URL is leaked or compromised, regenerate it immediately from the monitor settings.

Use HTTPS

Always use https:// when calling the heartbeat URL to prevent interception.

Store the URL Securely

Don't hardcode heartbeat URLs in public repositories. Use:

  • Environment variables
  • Secret management tools (GitHub Secrets, HashiCorp Vault)
  • Configuration files with restricted access

Troubleshooting

Monitor Shows Down But Job Ran

  1. Check the ping reached UptimeObserver — Verify the curl/wget command succeeded (check exit codes, network logs)
  2. Incorrect URL — Confirm you're using the correct heartbeat URL from the monitor settings
  3. Firewall blocking outbound traffic — Ensure your server can reach uptimeobserver.com on port 443
  4. DNS resolution — Verify your server can resolve uptimeobserver.com

Ping Sent but Not Registered

  1. HTTP method — UptimeObserver accepts GET, POST, and HEAD requests. Ensure your client isn't using an unsupported method
  2. Response status — A successful ping returns HTTP 200. Check if your client is receiving errors
  3. Rate limiting — Multiple pings within a short window are fine, but excessive bursts may be throttled

Script Fails But Monitor Stays Up

This happens if you're calling the heartbeat URL unconditionally (before the job runs, or regardless of success):

# BAD — pings even if backup fails
curl https://uptimeobserver.com/ping/YOUR-ID
/usr/local/bin/backup.sh

# GOOD — only pings on success
/usr/local/bin/backup.sh && curl https://uptimeobserver.com/ping/YOUR-ID

False Alerts From Slight Delays

If your job occasionally runs a few minutes late but still completes:

  1. Increase the grace period to account for normal variation
  2. Adjust the interval if your job's schedule is less predictable than you configured

Monitor Not Appearing in Dashboard

  1. First ping hasn't arrived — New monitors start in a "pending" state and only appear active after the first ping is received
  2. Check the URL — Verify you copied the full heartbeat URL correctly

Need Help?

If you need assistance configuring heartbeat monitoring, reach out using the "Need Help?" button on the bottom right corner or email us at support@uptimeobserver.com.