Cron Heartbeats

A scheduled job that silently stops running is one of the easiest failures to miss — there's no error, just nothing. Heartbeats make a job report when it starts, finishes, and how it went, so Hexcovery can tell you when a run failed or never happened.

Wrap any periodic task — a nightly backup, a batch import, a periodic sync — with a few simple HTTP calls. The jobs then appear on the Cron Jobs dashboard page.

The heartbeat API

Every call is an HTTP request to /api/v1/heartbeat/<job_name>/<action>, authenticated with your API key in the X-API-Key header. There are four actions:

Action	Method	When to call it
`start`	POST	At the beginning of a run
`log`	POST	During a run, to attach a message (request body, up to 10 KB)
`end`	POST	At the end of a run, reporting success or failure
`ping`	GET or POST	A single liveness signal for jobs you don't bracket with start/end

The end action takes optional query parameters:

status — ok (default) or fail.
exit_code — the process exit code, 0–255.
duration_ms — the run duration in milliseconds.

For the complete request/response reference, see the Heartbeat API.

Bracket a job with start / end

The common pattern is to call start before the work and end after, reporting the outcome:

API_KEY=YOUR_API_KEY
BASE=https://ingest.hexcovery.com/api/v1/heartbeat/nightly-backup

curl -s -X POST "$BASE/start" -H "X-API-Key: $API_KEY"

if ./run-backup.sh; then
  curl -s -X POST "$BASE/end?status=ok" -H "X-API-Key: $API_KEY"
else
  curl -s -X POST "$BASE/end?status=fail&exit_code=$?" -H "X-API-Key: $API_KEY"
fi

For a simpler job you just want to know is alive, a single ping per run is enough:

curl -s "https://ingest.hexcovery.com/api/v1/heartbeat/cache-warmer/ping" \
  -H "X-API-Key: YOUR_API_KEY"

Hexcovery infers each job's expected interval from the gaps between runs, so once a job has a history it can flag a run as overdue when the next heartbeat doesn't arrive on schedule.

Exact endpoint value

Your organization's exact ingest endpoint is shown in the dashboard. Use that value rather than the placeholder above.

Attribute a job to a host, service, and Project

Optionally attach three headers to any heartbeat to place the job in context:

Header	Maps to
`X-Hexcovery-Host`	The host the job ran on
`X-Hexcovery-Service`	The `service.name` (the entity)
`X-Hexcovery-Project`	The `service.namespace` (the Project)

curl -s -X POST "$BASE/start" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Hexcovery-Service: orders-api" \
  -H "X-Hexcovery-Project: superpippo" \
  -H "X-Hexcovery-Host: worker-03"

With a Project set, the job shows up alongside that Project's other signals; with a host set, it feeds the Project's infrastructure view. See Services and Projects for the model.

Attach a message

Use log to record a line of detail for a run — it's stored as the request body (up to 10 KB):

curl -s -X POST "$BASE/log" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data 'backed up 4,210 rows to s3://backups/2026-06-21'

See your jobs

Every job that has reported a heartbeat appears on the Cron Jobs page, with its recent run statuses, last outcome, average duration, and overdue flags.