How It Works
Understand heartbeats, ping URLs, schedules, states, and grace time.
Heartbeats
A Heartbeat represents a single job or process you want to monitor. Create one heartbeat per job — for example, one for your nightly database backup and another for your hourly report generation.
Each heartbeat has a unique Ping URL. Your job makes an HTTP request to that URL every time it runs successfully. Cronping uses the presence (or absence) of those pings to determine whether the job is healthy.
Ping URL
Every heartbeat gets a unique URL in the form:
https://ping.cronping.com/<token>The <token> is a random secret string. Treat it like a password — anyone with the URL can send signals to your heartbeat.
Cronping accepts GET, POST, and HEAD requests, so you can use any HTTP client, from curl to a full HTTP library.
Ping types
Besides the default success ping, Cronping supports additional signal types via URL suffixes:
| Endpoint | Signal | Effect |
|---|---|---|
/<token> | Success | Job completed OK — status set to Up |
.../start | Start | Job is running — enables duration tracking |
.../fail | Fail | Job failed — status set to Down immediately |
.../<exit-code> | Exit code | 0 = success, 1-255 = failure |
.../log | Log | Attach a log entry without changing status |
When a /start ping is followed by a success or fail ping, Cronping automatically measures the run duration and shows it in the ping history.
See the Ping API Reference for full details, response schemas, and examples.
Schedules
You can configure a heartbeat with one of two schedule types:
Interval
The job runs at a fixed interval — e.g. every hour, every 24 hours, every 7 days.
| Field | Example | Meaning |
|---|---|---|
| Interval | 86400 seconds | Expect a ping once per day |
Cron expression
The job runs at specific times defined by a cron expression. Cron gives you exact control (e.g. "every Monday at 3 AM") and supports timezone configuration.
| Field | Example | Meaning |
|---|---|---|
| Cron | 0 3 * * 1 | Every Monday at 3:00 AM |
| Timezone | America/Sao_Paulo | Evaluate the schedule in this timezone |
Cron syntax
Use * * * * * format: minute, hour, day-of-month, month, day-of-week. See
examples in Monitoring Cron Jobs.
Grace Time
Grace Time is extra tolerance added on top of the schedule before Cronping declares a heartbeat Down and sends alerts.
This accounts for minor, expected delays in job execution — for example, a backup that usually finishes in 2 minutes but occasionally takes 6.
Default grace time is 5 minutes.
Example
A heartbeat with interval 1 hour and grace time 5 minutes:
| Time | Event |
|---|---|
| 12:00 | Ping received |
| 13:00 | Expected next ping — heartbeat enters Late state |
| 13:05 | Grace time expires — heartbeat enters Down state and alerts fire |
Heartbeat States
Each heartbeat is always in one of the following states:
| State | Meaning |
|---|---|
| New | Heartbeat created but has never received a ping. |
| Up | All good. The last ping arrived on time. |
| Late | A ping is overdue but still within the grace period. No alert yet. |
| Down | Grace period has expired. Alerts have been sent. |
| Paused | Monitoring is manually suspended. Pings are still accepted but do not change state. |
Cronping sends an alert when a heartbeat transitions to Down. It sends a recovery alert when it receives a ping after being Down.
Repeated Reminders
By default, Cronping sends a single alert when a heartbeat goes Down. If you enable Repeat Reminders on a heartbeat, Cronping will continue sending periodic reminder notifications as long as the heartbeat stays down.
Available intervals: 1 hour, 6 hours, 12 hours, 24 hours, 3 days, 7 days.
Configure this per-heartbeat in the edit form under Notifications → Repeat reminders.
Tags
Every heartbeat can have tags — space-separated labels you assign for organizing and filtering. For example: production database critical.
Tags appear in the heartbeat list and detail views. Use the tag filter in the list view to quickly find heartbeats by tag.
Cloning Heartbeats
You can clone any existing heartbeat. This creates a new heartbeat with the same configuration (schedule, grace period, tags, integrations) but a fresh token. Perfect for setting up similar monitors quickly.
Use the Clone button on the heartbeat detail page or the dropdown menu in the list view.
Weekly Reports
Cronping sends a Weekly Report email to all organization members every Monday at 9:00 AM UTC. The report includes:
- Total heartbeats, down events, and alerts sent in the past 7 days
- Per-heartbeat status, uptime percentage, and alert count
Weekly reports are sent automatically — no configuration needed.
Integrations
An Integration is a notification channel — the place where Cronping sends alerts when a heartbeat goes down or recovers.
Each organization can have multiple integrations. When creating or editing a heartbeat, you can choose which integrations it uses, or rely on the organization-wide defaults.
Supported channels:
- Email — enabled by default for every heartbeat
- Webhook — POST a JSON payload to any URL
- Slack — send formatted messages to a channel
- Discord — send messages to a server channel
- Telegram — send messages via a Telegram Bot
- Microsoft Teams — post to a Teams channel
- PagerDuty — send incidents to your on-call rotation
See Integrations for setup instructions.
Alert Rules
Alert Rules evaluate fields from JSON ping payloads to catch silent failures — jobs that report success but didn't actually do useful work.
For example, a backup job might complete without errors but export 0 rows. With an alert rule like rows_processed < 1 → fail, Cronping catches this automatically and marks the heartbeat as Down.
Each heartbeat can have up to 20 rules with configurable operators (==, !=, >, >=, <, <=, contains, not contains) and actions (Fail or Warn).
Configure rules in the heartbeat edit form under Alert Rules. See the Alert Rules guide for full documentation and examples.
Overlap Detection
Overlap Detection monitors for concurrent job executions. When a /start ping arrives while a previous run is still open, Cronping flags it as an overlap event.
Three modes are available per heartbeat:
| Mode | Behavior |
|---|---|
| Off | Ignore overlapping runs (default) |
| Warn | Log the overlap event, don't change status |
| Fail | Treat as failure — heartbeat goes Down, alerts fire |
Configure this per-heartbeat in the edit form under Notifications → Overlap detection.
Log Context in Alerts
When an alert fires, Cronping automatically includes the most recent log output from the heartbeat's ping history. This eliminates the need to SSH in to diagnose failures.
Log data is sourced from the request body of POST pings — send your script's output with the ping and it will appear in every alert notification across all channels.
See Alert Rules — Log context in alerts for details and examples.