Turn a Node.js health check into an actionable alert
A small scheduled Node.js check that updates a Butters health card and sends a failure event with the endpoint, response time, and reason.
A cron job can tell you that a service is down. The useful version tells you which service, what failed, and whether the latest check has recovered. You can get that with one Node.js script and two Butters calls: update an insight card on every run, then send an event when a check fails.
This example probes an HTTP health endpoint once per run. It does not replace a dedicated uptime monitor, but it gives a small team a readable status card and a failure record in the same place as its other operational events.
Set up a server-only check
Use Node.js 20 or newer for built-in fetch and AbortSignal.timeout. Install the SDK with npm install @getbutters/js. Give the scheduled process these environment variables:
BUTTERS_API_KEY=ev_your_secret_key
BUTTERS_PROJECT_ID=your_project_id
HEALTH_URL=https://example.com/health Use a health URL that is safe to call repeatedly and returns a non-2xx status when the service cannot perform its essential work. Store the event key in your scheduler's secret store, not in the script or a committed .env file.
Write one check
Create scripts/check-health.mjs:
import { Butters } from '@getbutters/js/server'
const butters = new Butters({
key: process.env.BUTTERS_API_KEY,
project: process.env.BUTTERS_PROJECT_ID,
})
const healthUrl = process.env.HEALTH_URL
if (!healthUrl) throw new Error('HEALTH_URL is required')
const started = performance.now()
let failure = null
try {
const response = await fetch(healthUrl, {
signal: AbortSignal.timeout(5000),
})
if (!response.ok) failure = 'HTTP ' + response.status
} catch (error) {
failure = error instanceof Error ? error.message : 'Request failed'
}
const durationMs = Math.round(performance.now() - started)
await butters.setInsight('API health', failure ? 'Down' : 'Healthy', '🩺')
if (failure) {
await butters.track('health', 'API health check failed', {
description: failure,
metadata: { endpoint: new URL(healthUrl).pathname, duration_ms: durationMs },
notify: true,
})
process.exitCode = 1
} The insight title is stable, so each run updates the same card. A failed request produces an event and a nonzero process exit. notify: true asks Butters to send the event to the project's configured notification destinations; configure those destinations first if you want a phone or chat alert.
The event stores only the URL path, not the full URL. Health URLs sometimes contain credentials or tokens in their query string. If you monitor several services, use a distinct insight title and a safe service name in the event metadata.
Schedule it without creating noise
Run node scripts/check-health.mjs manually once while the endpoint is healthy, then once with a test endpoint that returns 503. In cron, a daily check at 08:00 in the host's timezone looks like this:
0 8 * * * cd /path/to/app && node scripts/check-health.mjs The cron process also needs the three environment variables. A scheduler that supports secrets is a better place for them than a crontab line. For a short outage, a daily check may miss the problem entirely; choose a cadence based on how quickly your team needs to know.
As written, every failed run sends another alert. For a frequent schedule, keep the previous health state in durable storage and notify only on the transition from healthy to down. Send a separate recovery event on the transition back to healthy. Keep updating the insight every run so the card reflects the latest check.
Test failure of the reporting path
If Butters is unreachable, setInsight or track rejects and the process exits nonzero. That makes the scheduler's own failure signal useful. Do not blindly retry track after a timeout: the server may already have accepted the event. Check the Butters feed and your scheduler logs when the result is uncertain.
The Butters JavaScript SDK guide lists the server methods and event fields. This script uses the current server client, not the browser's publishable-key entry point.