Heartbeat Monitoring

A Heartbeat monitor (often called a dead man's switch) works in reverse compared to standard monitors. Instead of Pinger actively reaching out to your service, your service actively pings Pinger at a regular interval. If Pinger does not receive a ping within the expected timeframe, an incident is triggered.

When to use Heartbeats

Heartbeat monitors are ideal for:

• Cron jobs and scheduled tasks (e.g., database backups, daily reports).
• Background workers and queue consumers.
• Services running in private networks or behind NATs where inbound traffic is blocked.

Configuration

When you create a Heartbeat monitor, Pinger generates a unique heartbeatSecret for it. You configure an intervalSeconds (how often you expect it to ping) and a gracePeriodSeconds(how late it can be before triggering an alert).

Integration Guide

Once you have your heartbeat secret, you must send an HTTP POST request to the reporting endpoint. The secret must be included in the URL path.

curl -X POST https://api.pingr.site/api/heartbeat/your_heartbeat_secret_here

// Run this at the very end of your cron job
async function reportSuccess() {
  await fetch('https://api.pingr.site/api/heartbeat/your_heartbeat_secret_here', {
    method: 'POST'
  });
}

import requests

# Run this at the very end of your cron job
def report_success():
    requests.post('https://api.pingr.site/api/heartbeat/your_heartbeat_secret_here')

Production Recommendations

Rate Limiting & Limitations

Heartbeat endpoints are strictly rate-limited to 1 request per second per monitor to prevent accidental infinite-loop DoS attacks. If you ping more frequently than once per second, you will receive a 429 Too Many Requests response.

Responses

• 200 OK: Heartbeat successfully recorded.
• 404 Not Found: Invalid or revoked heartbeat secret.
• 429 Too Many Requests: Pinging too fast (less than 1 second apart).