Healthchecks.io

Healthchecks.io watches your cron jobs and scheduled tasks, and its Webhook integration tells Pocketbell when a check goes down or comes back up. There are two ways to set it up:

• Quick: a webhook Source. Paste its URL into Healthchecks.io with the body below, and there’s nothing to set in the app: Pocketbell knows this body. A check that goes down is a Critical notification that repeats until you acknowledge it, for up to an hour, and the all-clear stops it when the check is back.
• Your own body: an API Source, for choosing every field of the notification yourself, such as a link to the check.

Pick one; the two use different URLs and bodies.

Quick: a webhook Source

1. In the Pocketbell app, create a Source named Healthchecks.io, choose Webhook, and leave its priority on Normal, so a check that goes down is Critical (another default makes every event that priority). Copy its URL, https://api.pocketbell.dev/v1/hooks/pbw_….

2. In Healthchecks.io, open Integrations, add a Webhook, and name it Pocketbell.

3. Under Execute when a check goes down, change GET to POST. A Request Body field appears. Paste the Source’s URL as the URL, and this as the Request Body:

   {"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "check": "$CODE"}

   Leave Request Headers empty: the URL is all a webhook Source needs.

4. Under Execute when a check goes up, do the same: POST, the same URL and the same body.

5. Save the integration, then click Test! beside it.

6. The test arrives as TEST is down. There’s nothing to set in the app: Pocketbell recognizes the body, the Source’s setup shows what each event becomes, and its Notification Content says Automatic (Healthchecks.io). Customize… is there if you want your own words.

7. Turn the integration on for each check that should alert you: on the Checks page, click its icon in the check’s row, or use the ON/OFF switch on the check’s page.

A check named Backups that goes down arrives as Backups is down, “It missed its check-in.”, a Critical notification that repeats until you acknowledge it, for up to an hour. Backups is back up arrives when it’s back, starting “Down for 12 min”: the repeats stop, and both stay in the inbox, in order. To change any of it, set your own title, message or priority in Notification Content: what you set wins, part by part. For no Critical notifications, set Priority by status with another priority for down. More in Webhooks.

Your own body: an API Source

1. In the Pocketbell app, create a Source named Healthchecks.io, choose API, and copy its key, pb_live_…. It’s shown only once.

2. In Healthchecks.io, add a Webhook integration named Pocketbell.

3. Under Execute when a check goes down, change GET to POST, and fill in:

   • URL: https://api.pocketbell.dev/v1/messages

   • Request Body:

     {
       "title": $NAME_JSON,
       "message": "Down: Healthchecks.io didn't hear from it on time.",
       "priority": "critical",
       "expire": 10800,
       "replace": "hc-$CODE",
       "tags": ["healthchecks"],
       "url": "https://healthchecks.io/checks/$CODE/details/",
       "url_title": "Open check"
     }

   • Request Headers, with your key in place of pb_live_…:

     Authorization: Bearer pb_live_…
     Content-Type: application/json

4. Under Execute when a check goes up, also POST, with the same URL and headers, and this body:

   {
     "title": $NAME_JSON,
     "message": "Back up.",
     "replace": "hc-$CODE",
     "tags": ["healthchecks"]
   }

5. Save, click Test!, and turn the integration on for your checks. The test arrives as a Critical notification named TEST that repeats until you acknowledge it, since no all-clear follows a test.

How it behaves

• Down repeats every five minutes for up to three hours, until someone acknowledges it on any device. Change expire (60 to 10800 seconds) or add "retry" (30 to 3600) to suit the check.
• Up carries the same replace key, hc- and the check’s code, so it takes the alert’s place, in the inbox and on screen, and the repeats stop.
• Every check needs a name: a check with none sends an empty title, which is refused.
• Open check opens the check in Healthchecks.io. If you run Healthchecks yourself, put your own address in url, or leave url and url_title out.

Placeholders

Healthchecks.io fills these in anywhere in a body:

Placeholder	Becomes
$NAME_JSON	The check’s name, as a JSON string, quotes included
$STATUS	down or up
$CODE	The check’s ID
$TAGS	The check’s tags, separated by spaces
$NOW	The time, in UTC
$EXITSTATUS	The exit status your job last reported, or -1

$NAME_JSON goes in without quotes of its own, so a check name with quotes in it still makes a valid request. Use it, not $NAME, for the name.

If a test doesn’t arrive, or reads wrong

• The notification reads “name: TEST · status: down · …”: the body isn’t the one above, all four fields, so Pocketbell doesn’t recognize it. Paste it again, for both the down and the up event.
• The notification reads “ is “ with no name or status: the Source is a webhook Source, but the body is the API Source’s. Use the body from Quick above.
• 401 invalid_api_key: an API Source’s key is wrong, or Bearer is missing in front of it.
• 400 invalid_request: the answer’s message says what to change. “The request body isn’t valid JSON”: check that $NAME_JSON has no quotes around it. “Send the body as JSON”: add the Content-Type header. Any other: details names the field that’s wrong or empty.
• 404 not_found: the webhook URL is incomplete, or the Source was deleted or its URL replaced.

Healthchecks.io shows Pocketbell’s answer when a notification fails, in the integration’s list and in the check’s event log.