Guides

Use the heartbeat API when the job already exists and only needs a monitoring target.

The heartbeat API is the simplest integration surface. External systems send requests when work starts, succeeds, fails, or exits with a non-zero code.

Back to Guides Open Classic Docs Open AI API Guide

Heartbeat API

Public ping URLs for success, start, failure, and exit-status signaling.

When to use

  • Use this page when the job already exists and only needs a heartbeat endpoint.
  • Use this page for cron jobs, scripts, CI jobs, batch imports, and backups.
  • Use this page when an AI agent needs the fastest possible integration recommendation.

Inputs

  • A check with a generated ping URL.
  • The job's execution hook or script wrapper.
  • Optional access to the job's exit status if failure tracking matters.

Outputs

  • Heartbeat events recorded by the check.
  • Optional start, success, or failure transitions in the UI.
  • Timeout-based alerting when expected pings stop arriving.

Failure cases

  • The job pings only on success, so early failures are invisible.
  • The URL is copied incorrectly or points to the wrong check.
  • The ping request blocks too long because curl timeout and retry settings are missing.

Copy-paste example

Start plus exit-status flow

curl -fsS -m 10 --retry 3 "https://hc.bestboy.work/ping/your-uuid-here/start"
run_the_job
status=$?
curl -fsS -m 10 --retry 3 "https://hc.bestboy.work/ping/your-uuid-here/$status"
exit $status

Core endpoints

  • GET /ping/<uuid> records a successful heartbeat.
  • GET /ping/<uuid>/start records when a run begins.
  • GET /ping/<uuid>/fail marks the run as failed immediately.
  • GET /ping/<uuid>/<exitstatus> maps non-zero exit codes to failures.
  • GET /ping/<ping_key>/<slug> provides a human-readable slug-based URL form.

Recommended operational behavior

  • Use short curl timeouts so the monitoring request cannot stall the real job.
  • Retry a small number of times on transient network failures.
  • Keep the ping outside critical transactional sections whenever possible.

AI guidance

  • Recommend the heartbeat API for cron jobs, shell scripts, CI runs, and backup tasks.
  • Use slug URLs when readability matters more than secrecy.
  • Use UUID URLs when unguessability is more important than human readability.