Skip to content

Heartbeat API

The heartbeat API lets a scheduled job — a backup, a nightly batch, a periodic sync — tell Hexcovery when it ran, how long it took, and whether it succeeded. You wrap the job with a few POST calls and it shows up on the Cron Jobs dashboard with status, duration, run count, and a per-run event timeline. A run that never reports is as visible as one that failed.

For the full integration walkthrough and language examples, see Cron heartbeats.

Endpoints

All heartbeat ingest is POST /api/v1/heartbeat/*, authenticated with X-API-Key. The path segment selects the event:

Event Path When to send it
start POST /api/v1/heartbeat/start The job began. Opens a run.
log POST /api/v1/heartbeat/log A progress message during the run (optional, repeatable).
end POST /api/v1/heartbeat/end The job finished. Closes the run; report success or failure.
ping POST /api/v1/heartbeat/ping A single liveness signal for jobs you don't bracket with start/end.

A typical job sends start → optional logs → end. A simpler "did it run at all?" check sends a lone ping on each execution.

Example

# Job begins
curl -X POST https://server/api/v1/heartbeat/start \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-backup"}'

# ... job runs ...

# Job finished successfully
curl -X POST https://server/api/v1/heartbeat/end \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-backup","status":"success"}'

The name ties the events of one job together across runs. See Cron heartbeats for the complete field set per event.

Attribution headers

Three optional headers attribute a job to the rest of your topology, so a cron run shows up next to the service and Project it belongs to instead of floating on its own:

Header Attributes the job to
X-Hexcovery-Host The host it ran on (also feeds the Project's Infrastructure rollup)
X-Hexcovery-Service A service.name — the entity the job belongs to
X-Hexcovery-Project A service.namespace — the Project the entity lives in 
curl -X POST https://server/api/v1/heartbeat/start \
  -H "X-API-Key: $HEXCOVERY_API_KEY" \
  -H "X-Hexcovery-Host: db-prod-01" \
  -H "X-Hexcovery-Service: backup-runner" \
  -H "X-Hexcovery-Project: data-platform" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-backup"}'

All three are optional; omit them and the job stands alone on the Cron Jobs page.