Documentation

Everything you need to set up checks and alerts.

Quick start

1. Sign up: enter your email and open the link we send.
2. Click “New check”, give it a name and the job’s schedule, for example 0 3 * * *.
3. Copy the ping URL and add it to the end of your job:

# crontab: nightly backup at 3:00, pings only when it succeeds
0 3 * * * /opt/backup.sh && curl -fsS -m 10 --retry 5 https://ping.heartcron.com/<uuid>

If the ping doesn’t arrive on time, Heartcron alerts you on the channels you connected: email, Telegram, Slack, Discord or a webhook.

Ping URLs

Every check has two URLs that work the same way:

• https://ping.heartcron.com/<uuid>: the check’s unique URL, shown on its page;
• https://ping.heartcron.com/<ping-key>/<slug>: a readable URL made of your project’s ping key (in project settings) and the check’s short name, such as nightly-backup.

GET, POST and HEAD all work. A ping to a paused check resumes it.

Signals

Sending /start before success also gives you the job’s duration in the event log.

Job output

Send up to 100 KB of output in a POST body. It is saved with the event and you can read it in the dashboard:

/opt/backup.sh 2>&1 | tail -c 100000 | curl -fsS -m 10 --data-binary @- https://ping.heartcron.com/<uuid>/$?

Schedules and grace periods

• Simple period: “every N minutes, hours or days” since the last ping.
• Cron expression with a time zone, for example 30 2 * * 1-5 in America/New_York. Daylight saving time is handled.
• Grace period: how long to wait after the expected time before alerting. It covers the job’s normal run time and small delays.

Statuses

You get one alert when a check goes down and one when it recovers, not one on every run.

Examples

Bash with an exit code

#!/bin/sh
URL=https://ping.heartcron.com/<uuid>
curl -fsS -m 10 "$URL/start"
/opt/report.sh
curl -fsS -m 10 --retry 5 "$URL/$?"

GitHub Actions

- name: Ping Heartcron
  if: always()
  run: curl -fsS -m 10 --retry 5 https://ping.heartcron.com/<uuid>/${{ job.status == 'success' && '0' || 'fail' }}

Kubernetes CronJob

command: ["/bin/sh", "-c", "/app/job && wget -q -T 10 -O /dev/null https://ping.heartcron.com/<uuid>"]

Python

import urllib.request
urllib.request.urlopen("https://ping.heartcron.com/<uuid>", timeout=10)

Each check’s page has ready-made snippets with its URL for crontab, Bash, Python, Node.js, PowerShell, GitHub Actions and Kubernetes.

Site checks

For sites and servers, Heartcron sends the requests itself, from several regions:

• HTTP: the status code (for example 2xx or 200,204), a keyword on the page, following redirects;
• TCP: whether a database, mail or game server port is open;
• SSL: certificate expiry, with a warning the number of days ahead you choose;
• Domain: domain registration expiry.

A check goes down only when it fails twice in a row in at least two regions, so one flaky network route won’t wake you at night. Checks run every 5 minutes on the Free plan and as often as every 30 seconds on Business.

Alerts

Connect channels on the project’s Integrations tab: email, Telegram, Slack, Discord and webhooks. Webhooks receive a JSON event with an X-Heartcron-Signature header (HMAC-SHA256 of the body with your secret). “Send test alert” checks a channel right away.

Responses and limits

Questions or ideas: hello@heartcron.com.