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

# Your First Heartbeat Monitor

> Create your first DevHelm heartbeat monitor to track cron jobs and background processes

By the end of this guide, you'll have a heartbeat monitor watching for periodic pings from your background job. If the ping stops arriving, DevHelm opens an incident.

<Accordion title="Prerequisites">
  * DevHelm CLI installed or an API token for REST calls
  * An API token set as `DEVHELM_API_TOKEN` — see [Authentication](/authentication)
  * A cron job, background worker, or scheduled task to monitor
</Accordion>

## How heartbeats work

Unlike other monitor types where DevHelm checks your service, heartbeat monitors work in reverse — **your service pings DevHelm**. If DevHelm doesn't receive a ping within the expected interval plus a grace period, it opens an incident.

## Create the monitor

<Steps>
  <Step title="Create the heartbeat monitor">
    <CodeGroup>
      ```bash CLI theme={null}
      devhelm monitors create \
        --name "Nightly Backup" \
        --type HEARTBEAT
      ```

      ```yaml devhelm.yml theme={null}
      version: "1"
      monitors:
        - name: Nightly Backup
          type: HEARTBEAT
          config:
            expectedInterval: 86400
            gracePeriod: 3600
      ```

      ```bash API theme={null}
      curl -X POST https://api.devhelm.io/api/v1/monitors \
        -H "Authorization: Bearer $DEVHELM_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Nightly Backup",
          "type": "HEARTBEAT",
          "config": {
            "expectedInterval": 86400,
            "gracePeriod": 3600
          }
        }'
      ```
    </CodeGroup>

    The CLI creates heartbeat monitors with a 60-second expected interval and grace period. For a daily job like this one, set `expectedInterval` and `gracePeriod` via YAML config-as-code or the API instead, as shown in the other tabs.

    The response includes a unique ping URL for this monitor.
  </Step>

  <Step title="Get the ping URL">
    ```bash theme={null}
    devhelm monitors get <monitor-id>
    ```

    Look for the `pingUrl` field — it looks like:

    ```
    https://api.devhelm.io/api/v1/heartbeat/<token>
    ```
  </Step>

  <Step title="Add the ping to your job">
    Add a curl call at the end of your cron job or scheduled task:

    ```bash theme={null}
    #!/bin/bash
    # Your backup script
    pg_dump mydb > /backups/nightly.sql

    # Ping DevHelm on success
    curl -fsS -o /dev/null https://api.devhelm.io/api/v1/heartbeat/<token>
    ```
  </Step>

  <Step title="Verify the first ping">
    Run your job once and confirm the ping arrived:

    ```bash theme={null}
    devhelm monitors checks <monitor-id> --limit 1
    ```
  </Step>
</Steps>

## Configuration fields

| Field              | Type    | Description                                              |
| ------------------ | ------- | -------------------------------------------------------- |
| `expectedInterval` | integer | Expected seconds between pings (e.g., `86400` for daily) |
| `gracePeriod`      | integer | Extra seconds to wait before declaring the job late      |

The monitor opens an incident if no ping arrives within `expectedInterval + gracePeriod` seconds after the last ping.

## Common patterns

<AccordionGroup>
  <Accordion title="Cron jobs">
    For a job that runs every hour, set `expectedInterval: 3600` and `gracePeriod: 300` (5 minutes of slack).
  </Accordion>

  <Accordion title="Kubernetes CronJobs">
    Add a curl sidecar or post-completion hook that pings DevHelm after the job container exits successfully.
  </Accordion>

  <Accordion title="Background workers">
    For long-running workers that process queues, add a periodic heartbeat in your main loop (e.g., every 5 minutes).
  </Accordion>

  <Accordion title="Ping only on success">
    Use `curl -fsS` so the ping is only sent on HTTP success. If your script fails, the ping is skipped and DevHelm eventually opens an incident.
  </Accordion>
</AccordionGroup>

<Warning>
  Heartbeat monitors cannot have probe regions — they rely on incoming pings from your infrastructure, not outbound checks.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Heartbeat reference" icon="heart-pulse" href="/monitoring/heartbeat/overview">
    Full heartbeat configuration and assertion details.
  </Card>

  <Card title="Cron job monitoring" icon="clock" href="/guides/cron-job-monitoring">
    Advanced patterns for scheduled task monitoring.
  </Card>

  <Card title="First alert" icon="bell" href="/guides/first-alert">
    Get notified when a heartbeat goes silent.
  </Card>
</CardGroup>