Heartbeats
How heartbeat monitoring works
Heartbeats tell you when a scheduled job stops running.
Your job sends a ping to OnlineOrNot after it finishes. If the ping does not arrive on time, OnlineOrNot alerts you.
Heartbeats work well for cron jobs, backups, data imports, certificate renewal, and other jobs that may fail without anyone noticing.
How missed pings detect failures
Each heartbeat has a secret URL on oonchk.com. Call this URL after your job succeeds:
backup_db_to_r2 && curl https://oonchk.com/your-heartbeat-id
The && means the ping is only sent if the backup succeeds. If the backup fails, no ping is sent and OnlineOrNot can alert you.
The heartbeat URL accepts HEAD, GET, and POST requests. OnlineOrNot counts the request itself as a ping. The request body does not matter.
Reporting schedules
You can choose a fixed interval or a cron schedule.
Fixed intervals
A fixed interval expects one ping every set number of seconds, minutes, hours, days, or weeks.
For example, a heartbeat with a 24-hour reporting period and a 30-minute grace period becomes overdue after 24 hours and 30 minutes without an accepted ping.
Cron schedules
Use a cron schedule when your job runs at a specific local time.
The grace period starts at the scheduled time. A job scheduled for 02:00 with 20 minutes of grace becomes overdue after 02:20.
OnlineOrNot checks deadlines about once a minute, so status changes may not happen at the exact second.
Grace periods and early pings
The grace period controls how late a ping can arrive before the heartbeat becomes down.
An unusually early ping may not change the next deadline. This prevents an extra run from hiding a later missed run.
Set the reporting schedule to match the job's real schedule, and send the ping when the job finishes. Check Last seen and the ping timeline to confirm that OnlineOrNot recorded it. A new ping may take a short time to appear.
Heartbeat states
| State | Meaning |
|---|---|
| Pending | Waiting for the first ping or the first ping after resuming |
| Up | Pings are arriving within the expected window |
| Down | The expected ping and grace period have passed |
| Paused | Monitoring and ping recording are stopped until manually resumed |
| Muted | Pings are recorded, but missed-ping state changes and alerts are disabled |
| Maintenance | A maintenance window has stopped missed-ping alerts |
A new heartbeat remains pending until its first ping. It does not become down before it has ever reported successfully.
The usual status changes are:
Pending -> Up -> Down -> Up
The first ping changes the heartbeat from pending to up. A missed deadline changes it from up to down. The next accepted ping changes it back to up.
Failure and recovery alerts
When a heartbeat becomes down, OnlineOrNot records an incident and sends failure alerts. You can send alerts by email, SMS, webhooks, and connected services such as Slack, Discord, Microsoft Teams, Telegram, and Pushover.
When the next ping arrives, OnlineOrNot closes the incident and sends recovery alerts. The first ping for a new heartbeat does not send a recovery alert because nothing failed.
A failed notification does not change the heartbeat's status.
Pausing, muting, and maintenance
These controls solve different problems:
- Pause stops monitoring and ignores incoming pings. Resuming returns the heartbeat to pending.
- Mute keeps recording pings but stops missed-ping alerts and status changes.
- Maintenance window stops missed-ping alerts on a schedule. Pings are still recorded, and the heartbeat returns to pending when maintenance ends.
See How maintenance windows work for more details.
Automatic status page incidents
A heartbeat can be linked to a status page component. When the heartbeat goes down, OnlineOrNot can create an incident on the status page.
When the heartbeat recovers, OnlineOrNot resolves the incident and marks the component as operational again.
Use this when a scheduled process is part of the customer-visible health of your service.
Keep the heartbeat URL secret
Anyone with the heartbeat URL can report a successful run. The URL does not require an API token or signed request.
Treat the URL as a secret. Avoid committing it to public repositories, including it in public logs, or sharing it outside the system that sends the heartbeat.
To create and connect a heartbeat, see Monitor cron jobs and scheduled tasks. To manage heartbeats with the API, see the Heartbeats API reference.