Ping a Heartbeat Monitor From Cron With curl: Flags and Pitfalls
Contents
For a cron heartbeat, use curl -fsS -m 5 -o /dev/null after &&, so the ping is sent only when the job succeeds, gives up after five seconds, and prints an error only when something is wrong. Keep the API key in a file curl reads, not on the crontab line, and escape every % in the crontab as \% or move the logic into a script. For start, complete, and fail reports with the job's exit code, use a wrapper script that returns the job's own exit status.
This guide covers curl 7.76 and later, cronie, and Debian's cron, checked against the curl man page and crontab(5) on November 16, 2026. Examples use CronRadar's ingestion API; the curl and cron details apply to any heartbeat service. For why a heartbeat catches failures that logs don't, see cron dead man's switch.
The One-Line Heartbeat#
30 2 * * * /opt/backup.sh && curl -fsS -m 5 -o /dev/null -K /etc/cronradar/curl.conf https://cron.life/api/v1/ping/nightly-backup/etc/cronradar/curl.conf holds one line, user = "ck_app_12345_abcdef:", so curl authenticates with HTTP Basic using the application's API key as the username and an empty password. nightly-backup is the monitor key. This form reports to a monitor that already exists; creating one from the ping needs the schedule parameter, covered below.
What Each Flag Does#
| Flag | Effect | Why it matters for a heartbeat |
|---|---|---|
-f, --fail |
Exit 22 on an HTTP status of 400 or more, without printing the body | A rejected ping (bad key, bad schedule) is an error, not a quiet success |
-s, --silent |
No progress meter, no messages | Keeps cron from mailing a progress bar |
-S, --show-error |
With -s, still print an error message |
You hear about failures, and only failures |
-m 5, --max-time 5 |
Cap each transfer at five seconds | A hung network can't hold the job open |
-o /dev/null |
Discard the response body | A successful ping produces no output to mail |
-K file, --config |
Read options from a file | Keeps the key off the command line |
By default, curl treats any HTTP response as success: a 401 for a revoked key exits 0, and nothing notices the monitor has stopped receiving pings. -f changes that.
--fail-with-body Needs curl 7.76.0#
--fail-with-body fails on the same statuses as --fail but keeps the response body, which for CronRadar is a JSON error such as MONITOR_NOT_FOUND with a message. It was added in curl 7.76.0, and the two options are mutually exclusive. Older distributions (RHEL 8 and Ubuntu 20.04 ship curl 7.61 and 7.68) reject it as an unknown option, which makes the whole ping fail every time. Check with curl --version, and use --fail-with-body while testing by hand, -f in production if your fleet has old hosts.
Timeouts#
--max-time limits each transfer, connection included. --connect-timeout limits only the connection phase and isn't a substitute: a server that accepts the connection and never answers is stopped only by --max-time. Five seconds is plenty for one small request and matches the timeout CronRadar's own SDKs use.
Retries, and Their Caveats#
--retry N retries "transient" errors: a timeout, or an HTTP 408, 429, 500, 502, 503, 504, 522, or 524 response. The first retry waits one second and each later one doubles the wait, and curl honors a Retry-After header. Three things to know before adding it:
--max-timeresets on each retry.-m 5 --retry 3can take well over 20 seconds. Add--retry-max-time 15to bound the total; a transfer already running is allowed to finish, so the real ceiling is a little higher.- A refused connection isn't transient. If the network isn't up yet, add
--retry-connrefused. --retry-all-errors(curl 7.71.0) retries everything, including a 400 for a malformed request or a 401 for a revoked key, which will fail identically each time. The man page calls it "the sledgehammer of retrying" and warns about "sending or receiving duplicate data." For a heartbeat, plain--retryis the better choice.
A retry can also deliver a request twice: the first attempt may have reached the server before the timeout fired. For a plain heartbeat that's harmless. For lifecycle events, send an Idempotency-Key header; CronRadar returns the original result for a duplicate key instead of applying it again.
30 2 * * * /opt/backup.sh && curl -fsS -m 5 --retry 2 --retry-max-time 15 -o /dev/null -K /etc/cronradar/curl.conf https://cron.life/api/v1/ping/nightly-backup&& Versus ;#
The operator between the job and curl decides what the ping means.
| Line | When curl runs | What the heartbeat proves |
|---|---|---|
job && curl ... |
Only if the job exits 0 | The job ran and succeeded |
job ; curl ... |
Always | Only that cron fired; failures look like success |
job || curl .../fail |
Only if the job fails | Failures, but not missed runs on its own |
Use &&. With ;, a backup that fails every night still pings every night, and the monitor stays healthy. With &&, a failed job sends nothing, and the monitor alerts once the expected time plus the grace period passes.
The line's exit status becomes curl's when curl runs and the job's when it doesn't. Cron itself doesn't act on exit status, so that's harmless on a crontab line, but it matters as soon as the line moves into a script that something else checks. The wrapper below keeps the job's status.
&& only works if the job's exit code is honest. A script that ends with echo done, or a pipeline whose last command succeeds, exits 0 after a failure; cron shell script best practices covers set -e and pipefail.
Escape % in the Crontab#
In a crontab command, an unescaped % is changed into a newline, and everything after the first one is sent to the command as standard input (crontab(5)). A heartbeat line breaks in two common ways:
# Broken: cron cuts the command at the first %, so curl never sees the rest.
0 3 * * * /opt/export.sh && curl -fsS -m 5 "https://cron.life/api/v1/ping/export?schedule=0%203%20*%20*%20*"
0 3 * * * /opt/export.sh --date "$(date +%F)" && curl ...
# Works: each % escaped with a backslash.
0 3 * * * /opt/export.sh --date "$(date +\%F)" && curl ...URL-encoded query strings and date formats are full of %. Escaping each one works, but the line gets hard to read and easy to break on the next edit. Once a heartbeat needs a schedule, a run ID, or a failure message, put it in a script, where % is just a character.
Keep the API Key Out of the Crontab#
Three places a key on the crontab line ends up:
- Mail. cronie and Debian's cron put crontab variables in the headers of the mail they send with a job's output, as cron "No MTA installed" shows from the source.
CRONRADAR_API_KEY=...at the top of a crontab leaks there. - Process listings and logs. A key in the URL path (
/ping/{key}/{api_key}) is visible inpswhile curl runs and in any proxy log on the way. Basic authentication keeps it out of the URL. - The command line itself. Even
-u "ck_app_...:"is exposed briefly: the curl man page says it hides the argument from process listings where it can, but it is "still visible for a moment before being cleared," and recommends reading such data from a file.
So read the key from a file only the job's account can read:
sudo install -d -m 0750 -o backup -g backup /etc/cronradar
sudo install -m 0600 -o backup -g backup /dev/null /etc/cronradar/curl.conf
sudoedit /etc/cronradar/curl.conf # user = "ck_app_12345_abcdef:"-K /etc/cronradar/curl.conf loads it without the key ever appearing in an argument. In a script, reading the key from a file and passing --user "$CRONRADAR_API_KEY:" keeps it out of the crontab and the URL, though not entirely out of process listings; -K avoids that too, which is why the wrapper below uses it. Cron environment variables shows other ways to load secrets for cron jobs. Use a separate CronRadar application and key per environment, so a staging host can't report to production monitors.
Start, Complete, and Fail With run_id#
A success-only ping can't tell a failed run from a missed one, and it says nothing about how long the job took. Reporting start, complete, and fail adds both, and a fail report alerts immediately instead of waiting for the grace period. This wrapper follows the lifecycle pattern in CronRadar's API reference: it reports start, runs the job, reports the outcome with the exit code, and exits with the job's own status:
#!/bin/sh
# /opt/backup-monitored.sh: run the backup and report its lifecycle to CronRadar.
url="https://cron.life/api/v1/ping/nightly-backup"
run_id="nightly-backup-$(date +%s)-$$"
report() {
event=$1
shift
curl --fail --silent --show-error --max-time 5 --output /dev/null \
--request POST --get --config /etc/cronradar/curl.conf \
--header "Idempotency-Key: $run_id-$event" \
--data-urlencode "schedule=30 2 * * *" \
--data-urlencode "gracePeriod=900" \
--data-urlencode "run_id=$run_id" \
"$@" "$url/$event" || true
}
report start
/opt/backup.sh
rc=$?
if [ "$rc" -eq 0 ]; then
report complete
else
report fail --data-urlencode "message=backup.sh exited with code $rc"
fi
exit "$rc"How it fits together:
--getwith--data-urlencodeputs each parameter in the query string, URL-encoded, so30 2 * * *arrives intact;--request POSTmakes it a POST, which the API recommends for lifecycle events. CronRadar accepts GET too.scheduleon every report means the first run creates the monitor, and a monitor deleted by accident comes back on the next run.gracePeriodis in seconds, minimum 60.run_idpairs the start with its outcome, so overlapping runs don't get mixed up. It's at most 128 characters.messagegoes only onfail, at most 1,000 characters. Send the exit code and a short reason, never logs, secrets, or customer data.--configsupplies the key for Basic authentication from the file created above.|| trueand--max-time 5keep a monitoring outage from failing the job or stalling it for more than a few seconds per report.exit "$rc"returns the backup's own status, so anything that checks the script still sees the real result.
The crontab line is just 30 2 * * * /opt/backup-monitored.sh, with no % and no key.
Test it by hand as the job's account before trusting it. Swap --fail for --fail-with-body and drop --output /dev/null in a copy, and you'll see CronRadar's JSON response, or its error and reason.
What You Get From CronRadar#
There's no CronRadar package for crontab and no discovery of crontab entries; each job reports with its own monitor key and schedule, as above. In return, a monitor that knows the schedule catches every way the job can go wrong. After the expected time plus the grace period with no report, the monitor goes from warning to critical and alerts by email, Slack, webhook, Discord, or PagerDuty. A fail report alerts immediately, and a start with no finish is flagged as stuck. Schedules are read in the application's time zone, an IANA name set in its settings (UTC when unset), so set it to the server's zone. For jobs inside a framework, the Laravel, Celery, Hangfire, and Quartz.NET integrations report without any curl. Plans are on the pricing page.
Frequently Asked Questions#
What curl flags should I use for a cron heartbeat?#
-fsS -m 5 -o /dev/null: fail on HTTP errors, stay quiet unless there's an error, give up after five seconds, and discard the response body. Add --retry 2 --retry-max-time 15 if the network is flaky, and -K with a config file to supply the key.
Why does my curl command work in the shell but not in crontab?#
Usually a %. Cron turns each unescaped % into a newline and sends the rest as standard input, which cuts URL-encoded query strings and date +%F short. Escape it as \% or move the command into a script. A minimal PATH in cron is the other common cause; use the full path to curl if it isn't in /usr/bin.
Should I use && or ; before the heartbeat curl?#
&&. It sends the ping only when the job exits 0, so a failing job stops pinging and the monitor alerts. With ; the ping is sent after every run, including failed ones.
Does --retry make a heartbeat more reliable?#
For transient errors such as timeouts and 5xx responses, yes, but bound it with --retry-max-time, because --max-time resets on each attempt. Avoid --retry-all-errors, which also retries requests that will fail the same way each time, like a bad key.
How do I keep the API key out of my crontab?#
Put it in a file only the job's account can read and load it with curl -K, or read it into a variable in a wrapper script. A key in the crontab can end up in cron's mail headers, and a key in the URL is visible in process listings and proxy logs.
Put this guide to work
Know when the next run is missing
Connect one scheduled job, confirm a real completion, then verify the alert destination. Keep your existing scheduler in charge of running the work.