Ping URL — Watchplane Docs

Your heartbeat’s ping URL is a unique endpoint that accepts GET or HEAD requests. No authentication is required — the URL itself is the secret.

https://watchplane.com/api/v1/heartbeat/{token}/ping

A successful ping returns 200 OK with a plain text body:

OK

Sending a ping

curl

curl -fsS https://watchplane.com/api/v1/heartbeat/TOKEN/ping

The -fsS flags suppress output but exit non-zero on failure, so your script can detect ping delivery failures.

cron

Append the ping to the end of your cron command:

# m h dom mon dow command
0 2 * * * /opt/scripts/backup.sh && curl -fsS https://watchplane.com/api/v1/heartbeat/TOKEN/ping

The && ensures the ping only fires if the backup script succeeds.

Node.js

import https from "node:https";

async function ping(token) {
  return new Promise((resolve, reject) => {
    https
      .get(`https://watchplane.com/api/v1/heartbeat/${token}/ping`, resolve)
      .on("error", reject);
  });
}

// After your job completes successfully
await ping("your-token-here");

Python

import urllib.request

def ping(token: str) -> None:
    urllib.request.urlopen(
        f"https://watchplane.com/api/v1/heartbeat/{token}/ping"
    )

# After your job completes
ping("your-token-here")

GitHub Actions

- name: Run backup
  run: /opt/scripts/backup.sh

- name: Ping Watchplane
  run: curl -fsS ${{ secrets.WATCHPLANE_PING_URL }}

Store the ping URL in a GitHub Actions secret to keep it out of your repository.

Best practices

Ping on success only — use && or equivalent to send the ping only when the job succeeds
Keep the token secret — anyone with the URL can send a ping; treat it like a password
Test the URL manually — curl it once to confirm it returns 200 OK before deploying
Use the grace period — set a grace period on the heartbeat to absorb normal execution variance

Troubleshooting

No ping received: Check your script is actually running. Look at ping history in the dashboard to see when the last ping was received.

Alert fires even though job ran: Your job likely ran but the ping curl command failed silently. Add -v to the curl command to debug.

Incorrect interval: The interval is in seconds. 3600 = 1 hour, 86400 = 24 hours.