Heartbeat
Get notified when something doesn't happen but you expected it to.
What it does
A Heartbeat Source alerts you when something stops checking in.
Before you start
You need a job that can send an HTTP request when it finishes successfully, and runs on a regular schedule.
Set it up
Copy the ping URL
After you add a Heartbeat, the Source's page shows a URL like https://prowl.boo/…. Anyone with the URL can keep the Heartbeat looking healthy, so treat it like a password.
(The short domain is a small joke: "boo!" is a kind of ping.)
Ping with the URL
Add a request to the end of your job. The "Cron example" on the Source's page looks like:
your-job.sh && curl -fsS --retry 5 --retry-all-errors https://prowl.boo/…
The && causes it to only ping Prowl when successful, and the --retry works around any transient network errors reaching Prowl. Any request method works except HEAD and OPTIONS: uptime checkers often send HEAD, so it doesn't reset the timer, and OPTIONS answers browsers' cross-origin checks, so a web page can ping too.
Choose a duration
Set a "Duration" longer than the time between runs, plus how long the job can take. You can choose a duration between 5 minutes and 365 days.
You can choose a duration that's well above your expected time if you want notifications only after a longer period of inactivity. For example, if you expect hourly pings you can set a 12-hour duration so you're only notified after it misses several pings.
Check it works
You won't receive a notification for a Heartbeat showing "Waiting for first ping". Prowl will remind you after 24 hours if it hasn't received a ping for a newly created Heartbeat, but only once. Run your job manually and make sure it's reporting into Prowl.
Options and behavior
Down alerts
When the duration passes without a ping you'll receive an alert within a minute or two. You can configure the exact event, description, link, and priority of this notification: choose an Emergency priority and you'll get notified with critical alerts on iOS if you've allowed them, for example.
If the Heartbeat goes up and down repeatedly, you won't get notified more often than once every 10 minutes or once per duration, whichever is longer, to prevent alert fatigue.
The notification's Application is the Source's name, or "Heartbeat" if you haven't named it.
Recovery notifications
When you enable "Notify me when it recovers", the first ping after a down alert sends the "Recovered" notification at its own "Recovery priority". An outage that recovers before it alerted doesn't send one.
Repeat the alert while it stays down
When you enable "Repeat the alert while it stays down", Prowl repeats the down alert at most once an hour, or once per duration if that's longer, and stops after seven reminders. Reminders use their own "Reminder priority", so you can send the first alert loudly and the reminders quietly.
Free alerts
Down alerts, recovery notifications, and reminders do not count toward your daily notification limit.
Changing the duration
A new duration takes effect immediately, measured from the last successful ping. This might mean you get a down alert right away if you set a lower duration. A Heartbeat that's already down stays down until its next ping.
Troubleshooting
It's still waiting for the first ping
Make sure the job actually runs, that it can reach prowl.boo, and that you're not using a HEAD request. You should run the command by hand to check that it's able to call Prowl without an error.
I get alerts but the job runs
- If you're using the cron-style
... && curl ...make sure the exit code of your job is0. - Check the "Recent pings" to see if the job is pinging. You might have an incorrect duration set.
- The job might take longer than the duration allows.
"Recent pings" is missing some pings
"Recent pings" shows only the last 20 pings. The list has minute-level granularity, so pings that land in the same minute are recorded once.
Disconnect or replace it
Pause and resume
A paused Heartbeat doesn't send alerts, but it still records pings. When you resume, a Heartbeat whose deadline passed during the pause gets a fresh window instead of alerting right away.
Rotate the URL
Choose "Rotate" to get a new URL to ping. The old URL stops working immediately, so update the job before it runs again.
Remove it
When you remove the Heartbeat, the ping URL will start failing with HTTP 404, which will show up as failed pings from your sending side.