Once the heartbeat monitor is created, the response returns a unique url — this is the endpoint your job or script must ping on each successful run. If a ping is not received within the configured interval, the monitor is marked as unhealthy and an alert is triggered based on your notification configuration.
How it works:
- Your cron job or script runs on its normal schedule.
- At the end of each successful run, it sends a GET request to the heartbeat URL returned in the creation response.
- If Pinghome does not receive a ping within the configured interval, it marks the monitor as unhealthy and sends an alert.
- If the job fails mid-run and never reaches the ping call, the missed ping triggers the alert automatically.
Common use cases:
- Cron job monitoring — Detect when a scheduled cron job fails silently, runs late, or is accidentally disabled on the server — issues that produce no error logs and are otherwise invisible.
- Queue worker health — Monitor whether background queue workers (e.g. Sidekiq, Celery, BullMQ) are actively processing jobs or have stalled due to memory issues, deadlocks, or crashes.
Authorization: Bearer YOUR_TOKEN
Expected Behavior:
- On success, returns a 201 with the heartbeat id and the unique url your job must ping. Store this URL securely — it is the only endpoint that keeps this monitor alive.
- The url only accepts GET requests, as shown in the methods array in the response.
- Set enabled: true to activate monitoring immediately after creation. Set false to create the monitor in a paused state.
- The interval defines how long Pinghome waits after the last ping before marking the monitor as unhealthy. Set this slightly longer than your job's expected runtime to avoid false alerts.
- If the request body is missing required fields, a 400 is returned.
- If authorization fails, a 401 is returned.