Heartbeat monitoring

Know when a scheduled job silently stops running.

Heartbeat monitoring is designed for cron jobs, backups, scheduled scripts, imports, reports, synchronization tasks, and other jobs that are expected to run on a schedule.

Heartbeat monitoring works differently

PingBeacons does not call your job. Your job calls PingBeacons using the unique heartbeat URL generated for that monitor.

1. How heartbeat monitoring works

1

Create a heartbeat monitor

PingBeacons generates a unique heartbeat URL for the monitor.

2

Add the heartbeat URL to your job

Configure your cron job or script to request the heartbeat URL when the job completes successfully.

3

Your job runs

The scheduled task performs its normal work, such as creating a backup or importing data.

4

The job sends a heartbeat

After successful completion, the job requests its PingBeacons heartbeat URL.

5

PingBeacons records the heartbeat

You can see when the latest heartbeat was received from the monitor.

2. Create a heartbeat monitor

1

Open your PingBeacons dashboard

Sign in and choose the option to create a new monitor.

2

Select heartbeat monitoring

Choose the heartbeat monitor type for the scheduled job you want to watch.

3

Give it a useful name

Use a name that clearly identifies the job, such as Daily Database Backup, Nightly Report, or Customer Sync.

4

Configure the expected schedule

Set the heartbeat timing according to how often the job is expected to run.

5

Save and copy the heartbeat URL

After creating the monitor, copy its unique PingBeacons heartbeat URL.

3. Send your first heartbeat

You can test the generated URL from a terminal using curl.

curl -fsS "YOUR_HEARTBEAT_URL"

Replace YOUR_HEARTBEAT_URL with the URL shown in your PingBeacons monitor.

Example structure

Your real heartbeat URL contains a unique token. Do not copy a heartbeat URL from another monitor or another user.

4. Add heartbeat monitoring to a cron job

A common setup is to send the heartbeat only when the main command finishes successfully.

0 2 * * * /path/to/backup.sh && curl -fsS "YOUR_HEARTBEAT_URL"
Why use &&?

With this setup, the heartbeat request runs only if the command before it exits successfully. If the backup command fails, the success heartbeat is not sent.

5. Shell script example

You can also place the heartbeat request at the end of a script.

#!/bin/bash
set -e

/path/to/backup-command

curl -fsS "YOUR_HEARTBEAT_URL"

Because set -e stops the script after an unsuccessful command, the heartbeat is only reached when the earlier work completes successfully.

6. Laravel scheduled job example

If your application uses Laravel's scheduler, you can send the heartbeat after a scheduled command succeeds.

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Schedule;

Schedule::command('backup:run')
    ->dailyAt('02:00')
    ->onSuccess(function () {
        Http::get(env('PINGBEACONS_HEARTBEAT_URL'));
    });

Store the heartbeat URL in your server environment instead of hard-coding the real token into source code.

PINGBEACONS_HEARTBEAT_URL=https://api.pingbeacons.com/h/YOUR_TOKEN

7. What should use heartbeat monitoring?

Database backups

Confirm that an important scheduled backup process continues to run.

Cron jobs

Watch scheduled server commands that could otherwise stop silently.

Imports and synchronization

Track recurring jobs that move data between applications or services.

Scheduled scripts

Monitor reporting, cleanup, maintenance, exports, and other recurring scripts.

8. What happens when a heartbeat is missed?

PingBeacons expects the monitor to receive heartbeats according to the configured timing. If an expected heartbeat does not arrive, the monitor can indicate that the scheduled job may not have completed as expected.

1

The job is expected to run

PingBeacons knows the timing configured for the heartbeat monitor.

2

No heartbeat arrives

The expected success signal is not received within the configured heartbeat timing.

3

A problem can be detected

The monitor can enter a problem state because the scheduled task did not report successful completion as expected.

4

You can be notified

Notification behavior follows the preferences configured in your PingBeacons account.

A missed heartbeat does not always mean the server is down

The job may have failed, stopped running, been delayed, or failed to reach the PingBeacons heartbeat endpoint. Investigate the job and its environment when a heartbeat is missed.

9. Heartbeat security

Treat the URL like a credential

Anyone who has the complete heartbeat URL may be able to send a heartbeat to that monitor.

Do not expose the token

Avoid public repositories, frontend JavaScript, screenshots, public documentation, logs, or other publicly accessible places.

Recommended environment variable

PINGBEACONS_HEARTBEAT_URL="YOUR_HEARTBEAT_URL"

Your application or script can read the heartbeat URL from the environment rather than storing the real token directly in the source code.

If a heartbeat URL becomes exposed

Stop using the exposed URL and replace it with a fresh heartbeat URL when token rotation or regeneration is available for the monitor.

10. Test your setup

Run the job manually

Execute the same command or script that normally runs from your scheduler.

Confirm the heartbeat was received

Open the heartbeat monitor in PingBeacons and verify that its latest heartbeat information was updated.

Confirm the scheduler is actually running

A heartbeat command inside a cron entry cannot help if the cron service or scheduler itself never runs.

Heartbeat vs normal monitoring

Website / API monitor

PingBeacons sends requests to your website or API and checks the response.

Heartbeat monitor

Your scheduled job sends a request to PingBeacons after it runs successfully.

Read API monitoring guide