Cron Monitors

Heartbeat monitoring for scheduled tasks -- cron jobs, background workers, queue consumers, batch processes, and anything else that runs on a schedule. Your task pings a unique URL when it runs. If Hoppla does not receive the ping on schedule, you get alerted.

How It Works

Each cron monitor has a unique ping URL. Your scheduled task sends an HTTP request to this URL after completing successfully. Hoppla tracks the time between pings and compares it to the schedule you configured.

If no ping arrives within the grace period after the expected run time, an incident is created and your configured notification channels are alerted.

The flow looks like this:

1. You create a cron monitor in the Hoppla dashboard and set its schedule (a cron expression).
2. You copy the unique ping URL and add it to your task.
3. Your task pings the URL each time it runs.
4. Hoppla watches for missed pings and alerts you if one is late.

Setting Up

1. Go to Monitors in the dashboard and click Add Cron Monitor.
2. Give the monitor a name that describes the task (e.g., "Nightly database backup").
3. Set the schedule as a cron expression (e.g., 0 * * * * for hourly, 0 0 * * * for daily).
4. Set the grace period in minutes -- how long after the expected time Hoppla should wait before alerting (default 5, minimum 1, maximum 1440).
5. Copy the generated ping URL.
6. Add the ping URL to your scheduled task (see examples below).

Integration Examples

Bash / Crontab

Append a curl call after your command. The && ensures the ping only fires if the command succeeds:

# Run backup every hour, ping Hoppla on success
0 * * * * /usr/bin/my-backup-script && curl -s https://app.hoppla.dev/api/ping/YOUR-UUID > /dev/null

PHP

Call the ping URL at the end of your scheduled task:

// At the end of your scheduled task:
file_get_contents('https://app.hoppla.dev/api/ping/YOUR-UUID');

Python

import requests

# Your task logic here
# ...

# Ping Hoppla when done
requests.get('https://app.hoppla.dev/api/ping/YOUR-UUID')

Node.js

// Your task logic here
// ...

// Ping Hoppla when done
fetch('https://app.hoppla.dev/api/ping/YOUR-UUID');

Laravel Task Scheduling

$schedule->command('app:daily-report')
    ->daily()
    ->thenPing('https://app.hoppla.dev/api/ping/YOUR-UUID');

Grace Periods

The grace period is the amount of time Hoppla waits after the expected ping before creating an incident. This accounts for tasks that occasionally run a bit late.

For example, if your task runs every hour and you set a 5-minute grace period:

• Expected ping: every 60 minutes
• Grace period: 5 minutes
• Alert after: 65 minutes of silence

Choose a grace period that matches the variability of your task. A nightly backup that sometimes takes an extra 10 minutes should have at least a 10-minute grace period.

Reporting State

A plain GET request to the ping URL is a simple liveness ping -- it tells Hoppla "I ran". To report a specific state, send a POST request with the value in the request body (form-encoded or JSON). A state passed as a query string on a GET is ignored.

# Report a failed run
curl -X POST https://app.hoppla.dev/api/ping/YOUR-UUID -d 'state=fail'

The accepted values are:

State	Meaning
start	Marks the beginning of a run. Paired with complete, it lets Hoppla measure the run's duration.
complete	Marks the successful end of a run started with start.
ok	Reports a successful run (a plain ping with no state is treated the same way).
fail	Reports that the task failed. Hoppla raises an incident immediately, without waiting for a missed ping.
log	A passive heartbeat that records the ping without changing the monitor's status.

To track how long a job takes, POST start when it begins and complete when it finishes:

curl -X POST https://app.hoppla.dev/api/ping/YOUR-UUID -d 'state=start'
# ... run the task ...
curl -X POST https://app.hoppla.dev/api/ping/YOUR-UUID -d 'state=complete'