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

# Heartbeat Monitors

> Monitor cron jobs and background processes with DevHelm heartbeat (passive) monitors

Heartbeat monitors work in reverse — instead of DevHelm checking your service, your service pings DevHelm at a regular interval. If a ping doesn't arrive within the expected interval plus grace period, an incident opens. This is ideal for monitoring processes that can't be reached from the outside.

<Tip>
  **Define this in code.** [YAML format](/mac/yaml/monitors) · [Terraform](/mac/terraform/monitors)
</Tip>

## When to use heartbeat monitors

* **Cron jobs** — verify scheduled tasks run on time
* **Batch processes** — confirm data pipelines complete their runs
* **Backup jobs** — detect when nightly backups don't finish
* **Queue consumers** — verify workers are processing messages
* **Scheduled reports** — confirm report generation runs

## How it works

1. You create a heartbeat monitor specifying the expected interval between pings
2. DevHelm generates a unique **ping URL** for the monitor
3. Your process calls the ping URL on each successful run
4. If the ping doesn't arrive within the expected interval plus the grace period, DevHelm marks the monitor as down and opens an incident

## Quick example

Create the monitor:

<CodeGroup>
  ```bash CLI theme={null}
  devhelm monitors create \
    --name "Nightly backup" \
    --type HEARTBEAT
  ```

  ```yaml devhelm.yml theme={null}
  monitors:
    - name: Nightly backup
      type: HEARTBEAT
      config:
        expectedInterval: 86400
        gracePeriod: 3600
      assertions:
        - config:
            type: heartbeat_received
          severity: fail
  ```
</CodeGroup>

The CLI creates heartbeat monitors with a 60-second expected interval and 60-second grace period. For custom intervals (like the daily backup above), use YAML config-as-code or the API, which accept `expectedInterval` and `gracePeriod`.

Then add the ping to your job:

```bash theme={null}
#!/bin/bash
# backup.sh
pg_dump mydb > /backups/$(date +%Y%m%d).sql

# Ping DevHelm on success
curl -s https://api.devhelm.io/api/v1/heartbeat/<ping-url-token>
```

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/monitoring/heartbeat/configuration">
    Expected interval, grace period, and heartbeat assertions.
  </Card>

  <Card title="Cron job monitoring guide" icon="clock" href="/guides/cron-job-monitoring">
    Patterns for background job monitoring.
  </Card>
</CardGroup>