# Heartbeat monitors A heartbeat monitor watches something that runs on a schedule, such as a cron job, a nightly backup or a queue worker. Instead of EvoHub checking a target, your job calls a unique URL each time it runs. If a call does not arrive in time, EvoHub marks the monitor down and alerts you, the way it would for any other monitor. ## When to use one Use a heartbeat monitor when the thing you care about has no address to check, or when "it ran" is what matters: - scheduled jobs and cron tasks - backups and data exports - background workers that should check in regularly - anything that fails silently by simply not running ## Create a heartbeat monitor :::steps ### Start a new monitor In **Uptime**, click **New Monitor**, enter a **Name**, and set **Monitor Type** to **Heartbeat (cron / job)**. ### Set the expected ping interval Under **Expected ping interval**, enter how often your job runs, as a number and a unit: minutes, hours or days. For example, `1 days` for a nightly job or `3 hours` for one that runs every three hours. ### Set the grace period Under **Grace period**, enter how late a ping may be before the monitor goes down, in minutes or hours. Allow for how long your job takes and how much its start time varies. ### Choose alerting Optionally pick an **Escalation Policy** under **Alerting** to page your team through On-Call. You can also add **Tags**. ### Create Click **Create Monitor**. The monitor's page shows its ping URL. ::: ## Ping the URL The monitor's page has a **Heartbeat ping URL** card with the address to call and a **Copy** button. The URL looks like `https://evohub.io/ping/`; always copy the exact one from the console. Call it at the end of your job, after the work has succeeded. `GET`, `POST` and `HEAD` all work, and no API key or other credential is needed. :::code-group ```bash [cron] # Runs at 02:00 every day, and pings only if the backup succeeds 0 2 * * * /usr/local/bin/backup.sh && curl -fsS https://evohub.io/ping/ ``` ```bash [shell script] #!/usr/bin/env bash set -euo pipefail ./run-export.sh curl -fsS --retry 3 https://evohub.io/ping/ ``` ::: A successful ping returns `200` with `{"status":"ok"}`. An unknown URL returns `404`. The card also shows **Last ping**, so you can confirm your job is reaching EvoHub. > [!WARNING] > The ping URL is the only credential. Anyone who has it can reset the monitor's timer. Keep it out of public repositories and logs. ## When a heartbeat goes down The monitor is down when the time since the last ping is longer than the expected interval plus the grace period. For example, with an interval of 1 day and a grace period of 30 minutes, a job that last pinged at 02:05 on Monday is marked down if no ping arrives by 02:35 on Tuesday. - A new monitor that has never been pinged gets one full interval plus grace, counted from when you created it, before it can go down. - When the monitor goes down, EvoHub opens an incident with the reason, for example "no heartbeat received for 25h0m0s", and alerts your notification channels and On-Call, just like a failed HTTP check. - While it stays down, you are alerted again on the monitor's **Re-alert while still down** schedule. - The next ping brings the monitor back up and closes the incident. ## How heartbeats differ from other monitors - There is no target, timeout, assertion, slow threshold or SLA target. - The monitor page records state changes rather than every ping, so **Recent Checks** shows when it went down and came back. - Heartbeat monitors are not metered for billing. ## Pause or silence a heartbeat **Pause** on the monitor's page stops it from being evaluated, for example while a job is switched off. To mute alerts for a planned window instead, use a silence window. See [Uptime alerts and silence windows](https://docs-dev.evohub.io/uptime-alerts-and-silence-windows.md#silence-windows). ## Related - [Uptime monitoring](https://docs-dev.evohub.io/uptime-overview.md) - [Uptime alerts and silence windows](https://docs-dev.evohub.io/uptime-alerts-and-silence-windows.md) - [Escalation policies](https://docs-dev.evohub.io/escalation-policies.md)