Skip to content

Heartbeat Monitoring

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. If no ping arrives within the grace period, the monitor goes DOWN and triggers 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.

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 Twice-daily jobs
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: 5 minutes
  • 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.

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

# With POST + JSON metadata
0 2 * * * /usr/local/bin/backup.sh && curl -fsS -X POST -H "Content-Type: application/json" -d "{\"success\":true,\"exitCode\":$?,\"durationMs\":$(( $SECONDS * 1000 )),\"message\":\"Backup completed\"}" https://uptimeobserver.com/ping/YOUR-HEARTBEAT-ID

# 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.