Heartbeats

Heartbeat monitors ensure your cron jobs, scheduled tasks, and background workers are running on schedule. If a job misses its expected check-in, Pingura alerts you.

How it works

1. Create a heartbeat monitor and set the expected interval
2. Pingura generates a unique URL endpoint
3. Add a simple HTTP request to your job that pings that URL on completion
4. If no ping arrives within the interval + grace period, an alert fires

Creating a heartbeat

Go to Heartbeats → Create Heartbeat and configure:

• Name — e.g., "Nightly Database Backup"
• Expected interval — How often the job should check in
• Grace period — Extra time allowed before marking as missed
• Max consecutive misses — Missed check-ins before alerting (1–10)
• Notification channels — Which channels receive alerts

Integrating with your code

After creating a heartbeat, add a request to the unique URL at the end of your job:

Works with any language — Python requests.post(), PHP file_get_contents(), Node.js fetch(), or any HTTP client.

Reporting failures

Proactively report a job failure by appending /fail to the URL:

Exit code reporting

You can report the exit code of your job by appending it to the URL. An exit code of 0 is treated as success; anything else is a failure:

Sending metadata

You can optionally send metadata with each heartbeat ping. This data is stored and displayed in the Pingura UI alongside each check-in:

• status — A custom status string (e.g., "completed", "partial")
• message — A free-text message (e.g., "Processed 1,247 records")
• duration — How long the job took (e.g., "12.5s")

Send metadata as query parameters or JSON body:

The source IP address is also automatically captured with each ping.

Heartbeat history

Click any heartbeat to view check-in history, uptime percentage, timing graph, and export historical data. Each check-in entry shows the metadata you sent (status, message, duration) alongside the timestamp and source IP.