> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating A Heartbeat Monitor

> Step-by-step guide to set up your first heartbeat monitor in Checkly. Learn about configuration, timing, alerts, and best practices.

> [!TIP]
>
> Learn more about all the [Heartbeat Monitor capabilities](https://www.checklyhq.com/docs/detect/uptime-monitoring/heartbeat-monitors/overview.md) in the general overview.

Follow this comprehensive guide to create your first heartbeat monitor in Checkly. We'll walk through each configuration step and explain the best practices to ensure your monitoring is effective.

![Light mode interface](https://mintcdn.com/checkly-422f444a/x9HkiPSTkrv6lzMg/images/next/heartbeat-monitor-overview-light.png?fit=max\&auto=format\&n=x9HkiPSTkrv6lzMg\&q=85\&s=81717f24bc24a5c68e57ac855bb5d63c)

> **Prerequisites**
>
> Before creating your heartbeat monitor, make sure you have:
>
> * A Checkly account. Heartbeat monitors are available on all plans; see [pricing](https://www.checklyhq.com/pricing/) for limits
> * A scheduled job, script, or automated process you want to monitor
> * Access to modify the code/script that runs your task

## Step 1: Basic Configuration

Start by giving your monitor a descriptive name and relevant tags and description. Choose something descriptive that clearly identifies what the monitor is tracking, like "Nightly Database Backup" or "Weekly Reports Job".

Use tags to group related monitors and make them easier to find and manage.

## Step 2: Timing Configuration

The timing configuration is the heart of your heartbeat monitor. You need to specify when you expect pings and how much flexibility to allow.

### Period Setting

The **period** defines how often your task should ping Checkly:

* **Daily jobs**: Set to 1 day
* **Weekly jobs**: Set to 7 days
* **Hourly jobs**: Set to 1 hour

![Configure period and grace settings for your heartbeat monitor](https://mintcdn.com/checkly-422f444a/dC-9liJbfhShV5if/images/heartbeat-monitors/getting-started-period-and-grace.png?fit=max\&auto=format\&n=dC-9liJbfhShV5if\&q=85\&s=389f08e0ff79a079dd9a650f4d860cde)

### Grace Period

The **grace period** provides extra time before alerting, compensating for natural variance in job execution times:

**Common grace period examples:**

* **Daily backup at 2 AM** with 30-minute grace → Alert if no ping by 2:30 AM
* **Weekly report on Fridays** with 4-hour grace → Alert if no ping arrives within 4 hours of the expected time
* **Hourly sync job** with 5-minute grace → Alert if ping is more than 5 minutes late

> **Understanding Grace Periods**
>
> Grace periods compensate for natural variance in job execution times. For example:
>
> * **Daily backup at 2 AM** with 30-minute grace → Alert if no ping by 2:30 AM
> * **Weekly report on Fridays** with 4-hour grace → Alert if no ping arrives within 4 hours of the expected time
> * **Hourly sync job** with 5-minute grace → Alert if ping is more than 5 minutes late
>
> Choose grace periods based on:
>
> * Normal variance in your job execution time
> * Acceptable delay before you need to know about failures
> * Time needed for any retries or recovery processes

> **Timer Behavior**
>
> The heartbeat timer works predictably:
>
> * **First ping starts the timer** - When you send the first ping, monitoring begins
> * **Each ping resets the timer** - Every successful ping resets the countdown
> * **Alerts also reset the timer** - After an alert fires, the timer restarts
> * **Deactivation resets everything** - Pausing and resuming a monitor restarts timing
>
> This means if your job is supposed to run every 6 hours but runs late at hour 7, the next ping will be expected at hour 13 (7 + 6), not hour 12.
>
> ![Understanding how grace periods and timing work in heartbeat monitoring](https://mintcdn.com/checkly-422f444a/dC-9liJbfhShV5if/images/heartbeat-monitors/heartbeats-grace.jpg?fit=max\&auto=format\&n=dC-9liJbfhShV5if\&q=85\&s=a8213dd38b2b81678421b7540df90db7)

> **How to Choose the Right Grace Period**
>
> **Consider Your Job Variance**
>
> * How much does your job's runtime vary?
> * Account for network delays and system load
> * Include time for any retry logic
>
> **Balance Speed vs. False Alerts**
>
> * Too short: False alerts during normal delays
> * Too long: Slower failure detection
> * Start conservative, adjust based on experience

## Step 3: Alert Configuration

Connect your heartbeat monitor to [alert channels](https://www.checklyhq.com/docs/communicate/alerts/overview.md) to be notified when pings are missing.

### Choosing Alert Channels

**For immediate awareness:**

* **Email notifications** - Good for individual monitoring
* **Slack or Teams** - Great for team coordination and visibility

**For critical production jobs:**

* **PagerDuty** - Escalation and on-call management
* **Webhooks** - Custom integrations with your systems

**For different severity levels:**

* **Low priority**: Email only
* **Medium priority**: Slack + Email
* **High priority**: PagerDuty + Slack + Email

### Alert Timing

Configure when alerts should fire:

* **Run-based**: Alert after a set number of consecutive failures
* **Time-based**: Alert after the monitor has been failing for a set number of minutes
* **Reminders**: Send follow-up alerts at a set interval while the monitor keeps failing

All alert channels subscribed to the monitor are notified at the same time.

## Step 4: Ping URL and Implementation

Once created, your heartbeat monitor provides a unique ping URL. Your tasks should make an HTTP `GET` or `POST` request to this URL when they complete successfully.

## Step 5: Testing Your Setup

Before deploying to production, test your heartbeat monitor:

### Manual Testing

You can manually send pings through the Checkly interface to:

* Test your monitor setup before deployment
* Start the timer for a newly created monitor
* Silence alarms once a late job has finished

Manual pings are available both on the monitor detail page and in the quick actions menu from your monitors list.

![Send manual pings from the heartbeat monitor overview page](https://mintcdn.com/checkly-422f444a/dC-9liJbfhShV5if/images/heartbeat-monitors/heartbeat-ping-overview-page.png?fit=max\&auto=format\&n=dC-9liJbfhShV5if\&q=85\&s=967c5051e6176995dc66575e907d4875)

You can also send manual pings directly from your monitors list using the quick actions menu:

![Quick ping option in the heartbeat monitors list view](https://mintcdn.com/checkly-422f444a/dC-9liJbfhShV5if/images/heartbeat-monitors/heartbeat-ping-quick-menu.png?fit=max\&auto=format\&n=dC-9liJbfhShV5if\&q=85\&s=f7a98e17953b752cb27985b9e948947d)

## Common Configuration Patterns

**Daily Backup Job**

```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'

new HeartbeatMonitor('daily-backup-monitor', {
  name: 'Daily Database Backup',
  period: 24,
  periodUnit: 'hours',
  grace: 30,
  graceUnit: 'minutes',
  tags: ['backup', 'database', 'daily', 'production']
})
```

**Weekly Report Generation**

```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'

new HeartbeatMonitor('weekly-report-monitor', {
  name: 'Weekly Analytics Report',
  period: 7,
  periodUnit: 'days',
  grace: 4,
  graceUnit: 'hours',
  tags: ['reports', 'analytics', 'weekly', 'marketing']
})
```

**Hourly Data Sync**

```typescript theme={null}
import { HeartbeatMonitor } from 'checkly/constructs'

new HeartbeatMonitor('hourly-sync-monitor', {
  name: 'Hourly Customer Data Sync',
  period: 1,
  periodUnit: 'hours',
  grace: 10,
  graceUnit: 'minutes',
  tags: ['sync', 'data', 'hourly', 'critical']
})
```

## Best Practices for Pings

**Always include timeout and retry options:**

```bash theme={null}
# Good: With timeout and retries
curl -m 5 --retry 3 https://ping.checklyhq.com/your-id

# Bad: No timeout or retry protection
curl https://ping.checklyhq.com/your-id
```

**Position pings correctly in your code:**

```python theme={null}
# Good: Ping only after success
try:
    run_backup()
    upload_to_s3()
    # Only ping if everything succeeded
    requests.get(ping_url, timeout=5)
except Exception as e:
    # Don't ping on failure - let heartbeat alert
    log_error(e)
```

**Use source headers for tracking:**

```bash theme={null}
curl -H "Origin: backup-server-01" https://ping.checklyhq.com/your-id
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.