Heartbeats

A heartbeat is an inverted monitor: instead of Vantaj reaching out to check something, your job reaches in to say "I ran successfully." If the ping stops arriving, Vantaj alerts you.

This makes heartbeats the right tool for things that can fail silently — a cron job that crashes before completing, a backup script that never starts because the server rebooted, a worker process that stopped without raising an error.

How it works

1. You create a heartbeat and set how often your job is expected to run
2. Vantaj gives you a unique ping URL
3. Your job calls that URL at the end of each successful run
4. Vantaj checks every minute: if no ping has arrived within interval + grace, the heartbeat is marked missed

Status values

Creating a heartbeat

1. Go to Heartbeats in the left navigation
2. Click New heartbeat
3. Give it a name (e.g. Nightly backup, Invoice sync)
4. Set the schedule type and expected interval
5. Set a grace period
6. Click Create heartbeat — you'll see the ping URL immediately

Schedule types

Interval

Choose a preset interval — every 5 minutes, every hour, every day, and so on. Vantaj expects a ping every N minutes, plus the grace period.

Cron

Enter a cron expression (e.g. 0 3 * * * for 3 AM daily) and select a timezone. Use this when your job runs at a specific time of day rather than on a rolling interval.

minute · hour · day-of-month · month · day-of-week

Common examples:

Grace period

The grace period is extra time Vantaj waits after the expected interval before marking a heartbeat as missed. Use it to absorb legitimate delays — a job that usually runs in 30 seconds but occasionally takes 2 minutes under load.

For example, with a 1-hour interval and 5-minute grace, a heartbeat is marked missed only if no ping arrives within 1 hour and 5 minutes of the previous ping.

The ping URL

Each heartbeat has a unique URL like:

https://app.vantaj.co/api/hb/<token>

Call it with GET or POST — both work. Call it after your job completes successfully, not before. If your job fails partway through, don't call it — the missed ping is the signal.

Integration examples

Shell / cron — append to your cron command:

your-job && curl -fsS -m 10 --retry 3 https://app.vantaj.co/api/hb/YOUR_TOKEN

The && ensures the ping only fires if the job exits with code 0.

Node.js:

await runYourJob();
await fetch('https://app.vantaj.co/api/hb/YOUR_TOKEN');

Python:

run_your_job()
requests.get('https://app.vantaj.co/api/hb/YOUR_TOKEN', timeout=10)

Ping history

The heartbeat detail page shows:

• Last ping — how long ago the most recent ping arrived, updating live
• Last 24 hours — hourly bar chart of ping activity
• Recent pings — a log of the last 20 pings with timestamp, method, user-agent, and IP

What heartbeats don't replace

Heartbeats monitor whether a job ran — not whether it ran correctly. If your backup script runs but backs up 0 bytes, it will still ping successfully. Combine heartbeats with application-level checks (e.g. verify the backup file exists and has a non-zero size before calling the ping URL) for deeper coverage.