Heartbeats

Monitor cron jobs, scheduled tasks, and background processes with check-in based monitoring.

What are Heartbeats?

Unlike monitors that actively check your endpoints, heartbeats work in reverse - your jobs check in with Encompass to confirm they're running. If a check-in is missed, we alert you immediately.

Heartbeats are perfect for monitoring cron jobs, data pipelines, backup scripts, scheduled reports, and any other recurring task that should run on a schedule.

How It Works

1
Create a heartbeat
Define the expected schedule (e.g., "every hour" or "daily at 2am").
2
Get your unique URL
Each heartbeat has a unique check-in URL for your job to ping.
3
Add check-in to your job
Make an HTTP request to the check-in URL at the end of your job.
4
Get alerted on missed check-ins
If your job doesn't check in within the expected window (plus grace period), we alert you.

Creating a Heartbeat

Navigate to "Heartbeats" in the sidebar and click "Create Heartbeat". Configure the following:

Setting	Description
Name	A descriptive name (e.g., "Nightly Backup")
Schedule	How often the job should run (e.g., "every 1 hour", "every day")
Grace Period	Extra time to wait before alerting (accounts for job duration variance)
Timezone	Timezone for schedule calculation

Check-in Examples

Add a check-in call at the end of your job. Here are examples for common tools:

cURL (Shell)

# At the end of your cron job
curl -X POST https://api.encompass.gg/heartbeats/YOUR_ID/checkin

Python

import requests

def my_scheduled_job():
    # Your job logic here
    process_data()
    
    # Check in when complete
    requests.post("https://api.encompass.gg/heartbeats/YOUR_ID/checkin")

Node.js

const https = require('https');

async function myScheduledJob() {
  // Your job logic here
  await processData();
  
  // Check in when complete
  await fetch('https://api.encompass.gg/heartbeats/YOUR_ID/checkin', {
    method: 'POST'
  });
}

Crontab

# Run backup every night at 2am, then check in
0 2 * * * /usr/local/bin/backup.sh && curl -X POST https://api.encompass.gg/heartbeats/YOUR_ID/checkin

Heartbeat Status

Healthy

The job checked in on time. Everything is working as expected.

Missing

Expected check-in was not received within the grace period. An incident has been created.

Paused

Monitoring is disabled. No alerts will be sent for missed check-ins.

Waiting

Newly created heartbeat waiting for its first check-in.

Best Practices

Check in at the end of your job, not the beginning
Set a grace period that accounts for job duration variance
Use descriptive names to easily identify jobs in alerts
Handle check-in failures gracefully (don't let them crash your job)
Consider adding the check-in URL to environment variables for easy rotation

Monitors Incidents