Heartbeat Monitor Construct

Learn more about Heartbeat monitors in the Heartbeat monitor overview.

Use Heartbeat Monitors to track passive monitoring scenarios where external services ping Checkly at regular intervals. The examples below show how to configure monitoring for different types of scheduled jobs and services.

Prerequisites

Before creating heartbeat monitors, ensure you have:

An initialized Checkly CLI project
External services, cron jobs, or scripts that can send HTTP POST requests
Understanding of your scheduled job intervals and expected timing
Network access from your services to Checkly’s ping endpoints

For additional setup information, see CLI overview.

import { HeartbeatMonitor } from "checkly/constructs"

new HeartbeatMonitor("daily-backup-heartbeat", {
  name: "Daily Backup Job",
  description: "Expects a ping every **24h** from the nightly DB backup cron.",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
})

import { HeartbeatMonitor } from "checkly/constructs"

new HeartbeatMonitor("newsletter-heartbeat", {
  name: "Weekly Newsletter Job",
  description: "Weekly newsletter job completes every 7 days.",
  activated: true,
  muted: false,
  period: 7,
  periodUnit: "days",
  grace: 4,
  graceUnit: "hours",
  tags: ["newsletter", "marketing", "weekly"],
  alertChannels: [emailChannel, slackChannel],
})

Configuration

The Heartbeat Monitoring configuration consists of specific heartbeat monitoring options and inherited general monitoring options.

Heartbeat Monitor
General Monitor

Parameter	Type	Required	Default	Description
`period`	`number`	✅	-	The expected period between pings (30 seconds to 365 days)
`periodUnit`	`string`	✅	-	Time unit: `'seconds'` \| `'minutes'` \| `'hours'` \| `'days'`
`grace`	`number`	✅	-	Grace period before alerting (0 seconds to 365 days)
`graceUnit`	`string`	✅	-	Grace time unit: `'seconds'` \| `'minutes'` \| `'hours'` \| `'days'`

Property	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your monitor
`description`	`string`	❌	`null`	A description of the monitor. Supports markdown. Max 500 characters
`activated`	`boolean`	❌	`true`	Whether the monitor is enabled
`muted`	`boolean`	❌	`false`	Whether alert notifications are muted
`alertChannels`	`AlertChannel[]`	❌	`[]`	Array of AlertChannel objects for notifications
`tags`	`string[]`	❌	`[]`	Array of tags to organize monitors

`HeartbeatMonitor` Options

number

required

The expected period between pings from your external service. This defines how often your job or service should check in.Usage:

new HeartbeatMonitor('my-heartbeat', {
  name: "My heartbeat",
  period: 1,
  periodUnit: 'days' // Daily check-in expected
  /* More options ... */
})

Examples:

Daily Jobs
Hourly Tasks
Frequent Checks

// Daily backup job
new HeartbeatMonitor("backup-job", {
  name: "Daily Database Backup",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
})

// Hourly data sync
new HeartbeatMonitor("data-sync", {
  name: "Hourly Data Sync",
  period: 1,
  periodUnit: "hours",
  grace: 15,
  graceUnit: "minutes",
})

// Every 5 minutes
new HeartbeatMonitor("frequent-task", {
  name: "Frequent Health Check",
  period: 5,
  periodUnit: "minutes",
  grace: 2,
  graceUnit: "minutes",
})

Range: 30 seconds to 365 days

string

required

The time unit for the period. Defines whether the period is in seconds, minutes, hours, or days.Usage:

new HeartbeatMonitor("my-heartbeat", {
  name: "My heartbeat",
  period: 2,
  periodUnit: "hours" // Every 2 hours
  /* More options ... */
})

Available units: 'seconds', 'minutes', 'hours', 'days'

number

required

The grace period to wait before alerting after the expected ping time has passed. This allows for slight delays in job execution.Usage:

new HeartbeatMonitor('my-heartbeat', {
  period: 1,
  periodUnit: 'hours',
  grace: 10,
  graceUnit: 'minutes' // 10 minute grace period
})

Examples:

Short Grace Period
Moderate Grace Period
Long Grace Period

// Strict timing requirements
new HeartbeatMonitor("critical-task", {
  name: "Critical System Task",
  period: 5,
  periodUnit: "minutes",
  grace: 1, // Only 1 minute grace
  graceUnit: "minutes",
})

// Standard tolerance
new HeartbeatMonitor("standard-job", {
  name: "Standard Processing Job",
  period: 1,
  periodUnit: "hours",
  grace: 15, // 15 minute grace period
  graceUnit: "minutes",
})

// Flexible timing for complex jobs
new HeartbeatMonitor("complex-job", {
  name: "Complex Data Processing",
  period: 1,
  periodUnit: "days",
  grace: 4, // 4 hour grace period
  graceUnit: "hours",
})

Range: 0 seconds to 365 days

string

required

The time unit for the grace period. Defines whether the grace period is in seconds, minutes, hours, or days.Usage:

new HeartbeatMonitor('my-heartbeat', {
  period: 6,
  periodUnit: 'hours',
  grace: 30,
  graceUnit: 'minutes' // 30 minute grace period
})

Available units: 'seconds', 'minutes', 'hours', 'days'

General Monitor Options

string

required

Friendly name for your heartbeat monitor that will be displayed in the Checkly dashboard and used in notifications.Usage:

new HeartbeatMonitor('my-heartbeat', {
  name: 'Daily Backup Job Monitor',
  /* More options ... */
})

Examples

Daily Backup Job
Hourly Data Sync
CI/CD Pipeline
Log Processing
Short Interval Check

new HeartbeatMonitor("backup-job-heartbeat", {
  name: "Daily Database Backup",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
  tags: ["backup", "database", "critical"],
})

// Example cron job that would ping this heartbeat:
// 0 2 * * * /scripts/backup-database.sh && curl -X POST https://ping.checklyhq.com/[heartbeat-id]

new HeartbeatMonitor("sync-job-heartbeat", {
  name: "Hourly Data Synchronization",
  period: 1,
  periodUnit: "hours",
  grace: 15,
  graceUnit: "minutes",
  tags: ["sync", "data", "hourly"],
})

// Example Node.js job:
// setInterval(async () => {
//   try {
//     await syncData()
//     await fetch('https://ping.checklyhq.com/[heartbeat-id]', { method: 'POST' })
//   } catch (error) {
//     console.error('Sync failed:', error)
//   }
// }, 60 * 60 * 1000) // Every hour

new HeartbeatMonitor('deployment-heartbeat', {
  name: 'Production Deployment Pipeline',
  period: 2,
  periodUnit: 'hours',
  grace: 30,
  graceUnit: 'minutes',
  tags: ['deployment', 'ci-cd', 'production']
})

// Example GitHub Actions workflow step:
// - name: Ping Checkly on successful deployment
//   if: success()
//   run: |
//     curl -X POST https://ping.checklyhq.com/${{ secrets.HEARTBEAT_ID }}

new HeartbeatMonitor('log-processing-heartbeat', {
  name: 'Log Processing Job',
  period: 30,
  periodUnit: 'minutes',
  grace: 10,
  graceUnit: 'minutes',
  tags: ['logs', 'processing', 'monitoring']
})

// Example log processing service:
// const processLogs = async () => {
//   try {
//     await processLogFiles()
//
//     // Ping heartbeat on successful processing
//     await fetch(process.env.CHECKLY_HEARTBEAT_URL, {
//       method: 'POST',
//       headers: { 'User-Agent': 'LogProcessor/1.0' }
//     })
//   } catch (error) {
//     console.error('Log processing failed:', error)
//   }
// }
//
// // Run every 30 minutes
// setInterval(processLogs, 30 * 60 * 1000)

new HeartbeatMonitor('frequent-task-heartbeat', {
  name: 'Every Minute Task',
  period: 60,
  periodUnit: 'seconds',
  grace: 30,
  graceUnit: 'seconds',
  tags: ['frequent', 'monitoring']
})

// Example for very frequent tasks:
// setInterval(async () => {
//   try {
//     await performQuickCheck()
//     await fetch('https://ping.checklyhq.com/[heartbeat-id]', { method: 'POST' })
//   } catch (error) {
//     console.error('Quick check failed:', error)
//   }
// }, 60000) // Every minute

Getting the heartbeat Ping URL

After deploying your heartbeat monitor, you can obtain the ping URL in several ways:

CLI Output
Web UI

npx checkly deploy

# Output will include:
# Ping URL of heartbeat check "[YOUR_HEARTBEAT_MONITOR_NAME]" is https://ping.checklyhq.com/...

The ping URL is unique for each heartbeat monitor and should be kept secure. Anyone with access to this URL can send pings to your monitor.

Heartbeat monitors are passive - they wait for your external services to ping them. Make sure your jobs and services are configured to send HTTP POST requests to the ping URL on successful completion.

Getting Started

DETECT

COMMUNICATE

Project & Configuration

Platform

Heartbeat Monitor Construct

Configuration

`HeartbeatMonitor` Options

General Monitor Options

Examples

Getting the heartbeat Ping URL

​Configuration

​HeartbeatMonitor Options

​General Monitor Options

​Examples

​Getting the heartbeat Ping URL

Configuration

`HeartbeatMonitor` Options

General Monitor Options

Examples

Getting the heartbeat Ping URL