Heartbeat Monitoring

How It Works

Unlike HTTP monitors where Pong checks your service, heartbeat monitors work in reverse — your service pings Pong to say “I’m alive.”

If Pong doesn’t receive a ping within the configured interval, the monitor is marked as down and alerts fire.

Setup

1. Create a monitor with type Heartbeat
2. Set the interval (e.g. 5 minutes for a cron job that runs every 5 minutes)
3. Copy the generated ping URL

Pinging

Add the ping to the end of your cron job or task:

# Crontab example
*/5 * * * * /path/to/my-job.sh && curl -s https://api.getpong.dev/api/v1/heartbeat/YOUR_TOKEN

Both GET and POST are supported:

# GET
curl https://api.getpong.dev/api/v1/heartbeat/YOUR_TOKEN

# POST
curl -X POST https://api.getpong.dev/api/v1/heartbeat/YOUR_TOKEN

The ping endpoint is public — no authentication needed. The token itself is the secret.

Secret Authentication

For extra security, you can require a secret when pinging the heartbeat endpoint. This prevents unauthorized actors from keeping a monitor alive by guessing or discovering the token URL.

Setup

When creating or editing a heartbeat monitor, fill in the Heartbeat Secret field. The UI provides a Generate button that creates a random 32-character hex string.

Usage

Include the secret in the X-Secret header:

curl -H "X-Secret: your_secret" https://api.getpong.dev/api/v1/heartbeat/YOUR_TOKEN

Behavior

• If a secret is configured, requests without a valid X-Secret header are rejected
• If no secret is set, the endpoint remains public (backward compatible with existing monitors)

Best practice

Store the secret in an environment variable rather than hardcoding it:

curl -H "X-Secret: $HEARTBEAT_SECRET" https://api.getpong.dev/api/v1/heartbeat/YOUR_TOKEN

Best Practices

• Ping after your job completes successfully, not before
• Set the interval slightly longer than your job’s schedule to account for execution time
• Use && to only ping on success: my-job.sh && curl ...