How to Monitor a Cron Job in Node.js

Steven Carver
Blog
Tutorials

Somewhere in your infrastructure, a cron job runs at 3am, and nobody checks whether it actually worked until something downstream breaks days later. That's the trouble with scheduled tasks: they don't have a user to complain when they fail, they just don't run, and Node's own error handling won't help you here since there's no request, no response, and often no process left alive to catch anything by the time someone notices.

A heartbeat monitor closes that gap. Your job pings a unique URL after it finishes, and if that ping doesn't show up on schedule, you get an alert instead of a surprise. Here's how to wire that into a Node.js cron job using the Downdar API.

What You Will Need

A Downdar API key from your account. Authentication is via Bearer token in the Authorization header. Your API key must always be kept server-side, never include it in browser-facing JavaScript.

Creating a Heartbeat Monitor

The /api/v1/heartbeats/create endpoint accepts a POST request with a name and returns the full heartbeat object, including the unique url your job will call on schedule. You only need to do this once per job, not on every run. If you'd rather skip the API for this part, you can also create a heartbeat directly from your Downdar dashboard and just copy the URL it gives you, the API call below is mainly useful if you want to provision heartbeats as part of a deploy script or automated setup.

// Run this once, server-side, to set up the heartbeat. const response = await fetch('https://downdar.com/api/v1/heartbeats/create', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'Nightly backup' }) });   const result = await response.json();

The response looks like this:

{ "ok": true, "heartbeat": { "guid": "550e8400-e29b-41d4-a716-446655440000", "name": "Nightly backup", "url": "https://downdar.com/heartbeats/550e8400-e29b-41d4-a716-446655440000", "paused": false }, "capacity": { "limit": 10, "used": 1, "remaining": 9 } }

Save the url field somewhere your job can reach it, an environment variable is the simplest option. You can also pass alert_channel_keys in the create request if you want this heartbeat routed to a specific Slack, Discord, or Telegram channel instead of the default.

Pinging the Heartbeat From Your Job

Once the heartbeat exists, the actual monitoring is a single HTTP request to its url at the end of a successful run. No library or SDK is required, any HTTP client will do.

async function runNightlyBackup() { try { await performBackup();   // Job succeeded, ping the heartbeat. await fetch(process.env.DOWNDAR_HEARTBEAT_URL, { method: 'GET', signal: AbortSignal.timeout(10000) }); } catch (err) { // Don't ping on failure, let the missed check-in trigger the alert. console.error('Backup failed:', err); } }   runNightlyBackup();

The important detail is in the catch block: only ping the heartbeat when the job actually succeeds. If the backup throws, skip the ping entirely, the heartbeat will notice the missing check-in on its own schedule and open an incident. This is what catches a silent failure, if you pinged unconditionally in a finally block instead, a broken job would still report as healthy.

If your job is a plain script rather than a long-running process, the same call works from crontab directly, without wrapping it in a try/catch at all:

# crontab: run the script, then ping only if it exits 0 0 3 * * * node /opt/scripts/backup.js && \ curl -fsS -m 10 https://downdar.com/heartbeats/550e8400-e29b-41d4-a716-446655440000

The && means curl only runs if the Node script exits successfully. If backup.js exits with an error, the ping never fires, and a missed check-in is exactly what should happen.

Checking Heartbeat Status Programmatically

If you want to surface a heartbeat's current state in your own dashboard or admin panel, the /api/v1/heartbeats/status endpoint returns just the essentials, lighter than a full get call.

const response = await fetch('https://downdar.com/api/v1/heartbeats/status', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.DOWNDAR_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ guid: '550e8400-e29b-41d4-a716-446655440000' }) });   const result = await response.json(); // result.status - "unknown", "up", "warn", "down", or "paused"

status reflects the heartbeat's current state directly, so you can show "last backup: healthy" somewhere your team already looks, without them needing to check Downdar itself.

A Note on API Key Security

Store your API key in an environment variable and never hardcode it.

// .env DOWNDAR_API_KEY=your_api_key_here DOWNDAR_HEARTBEAT_URL=https://downdar.com/heartbeats/your_heartbeat_guid   // Usage process.env.DOWNDAR_API_KEY

The heartbeat URL is fine to sit alongside your other deploy config, it only accepts check-ins and can't be used to read or change anything in your account. The API key is the credential that actually matters here, and it should never leave your server environment.

Get Started

Set up your first heartbeat from your account, or skip the dashboard entirely and create it straight from the API. Once it's wired into your job, the next scheduled run is the first thing it watches.

Start monitoring →