Heartbeat monitoring
Watch cron jobs, backups and workers with a simple HTTP ping.
A heartbeat monitor works the other way round: your job calls ResPulse when it runs. If a ping does not arrive on schedule, or the job reports a failure, the monitor goes DOWN. It is a dead man's switch for anything that should happen regularly.
Create a heartbeat monitor
- Add Monitor, type Heartbeat.
- Choose a name and a slug such as nightly-backup.
- Set how often the job runs (a fixed interval, or a 5-field cron expression with a time zone on Pro) and a grace period. The grace period is extra time allowed before the monitor is considered late, which prevents false alarms from slow runs.
- Copy the ping URL from the monitor card and add it to the end of your script.
Ping URLs
Every heartbeat has a private token URL and a readable URL built from your team Ping Key (shown on the Team tab) and the slug. Both accept GET and POST.
# Success curl -fsS -m 10 https://respulse.online/api/ping/<PING_KEY>/nightly-backup # Job started (lets ResPulse measure the duration) curl -fsS -m 10 https://respulse.online/api/ping/<PING_KEY>/nightly-backup/start # Job failed (DOWN immediately, with optional details in the body) curl -fsS -m 10 -d "pg_dump exited with errors" https://respulse.online/api/ping/<PING_KEY>/nightly-backup/fail # Pass the exit code of the previous command; 0 is success curl -fsS -m 10 --data-binary @output.log https://respulse.online/api/ping/<PING_KEY>/nightly-backup/$? # Log a note without changing the status curl -fsS -m 10 -d "step 2 of 5 done" https://respulse.online/api/ping/<PING_KEY>/nightly-backup/log
Signals
| URL ending | Meaning |
|---|---|
| (none) | The job finished successfully. |
| /start | The job started. When the success ping follows, the run duration is recorded. A job that started but never finishes is flagged as stuck. |
| /fail | The job failed. The monitor goes DOWN at once, an incident opens and alerts are sent without waiting for a timeout. |
| /<exit code> | Use the shell exit code. 0 means success, anything else is treated as a failure and includes the code. |
| /log | Stores the request body as a log line. The status does not change. |
Attaching output
The body of a ping is saved and shown in the dashboard and in incident reports, which is handy for error messages and stack traces. The Free plan keeps up to 512 bytes per ping, Pro up to 64 KB.
Create monitors from a script
Add ?create=1 to a ping for a slug that does not exist yet and the monitor is created on the spot. The first ping can describe it:
curl -fsS "https://respulse.online/api/ping/<PING_KEY>/web-1?create=1&interval=60&grace=120&name=Web+1&group=Servers&tags=prod,web"
- interval and grace are in seconds. The interval is never lower than your plan allows, and grace is at most 7 days.
- Without parameters a monitor for a daily job is created: interval 86400 s, grace 3600 s, group Background Workers, tag cron.
- A monitor that already exists is not changed by later pings.
Schedules (Pro)
Instead of a fixed interval you can use a standard 5-field cron expression such as 0 3 * * 1-5 (03:00 on weekdays) together with an IANA time zone such as Europe/Kyiv or America/New_York. The monitor expects a ping at each scheduled time plus the grace period.