CanaryAlertEarly Access
OverviewGetting StartedEmail ForwardingHTTP PingClassification RulesIntegrationsMaintenance WindowsSource GroupsReportsDigest Notifications

HTTP Ping Endpoint

Not everything sends email. For cron jobs, scripts, and services that can make HTTP requests, use the ping endpoint to report health directly. It works alongside email forwarding — every source gets both an inbound email address and a ping URL.

How it works

Each source gets a unique ping URL with an authentication token:

https://www.canaryalert.io/api/ping/SOURCE_ID?token=PING_TOKEN

You can find your source's ping URL on its detail page in the dashboard. Click the copy button to grab it.

Two modes

Simple ping (heartbeat)

Send a GET or POST request with no body. CanaryAlert records a SUCCESS event immediately — no AI classification needed. This resets the dead man's switch timer.

# Simple heartbeat — records SUCCESS

curl https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN

Use this at the end of a script or cron job to confirm it ran successfully.

Ping with message (AI classification)

Send a POST request with a JSON body containing a message field. CanaryAlert runs the message through AI classification using your source's rules, just like it does with emails.

# Ping with output — AI classifies it

curl -X POST \

https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN \

-H 'Content-Type: application/json' \

-d '{"message": "Backup completed: 12 VMs, 0 errors, 842 GB"}'

Use this when your script produces output you want classified (e.g., backup logs, test results, health check output). Messages can be up to 50 KB.

Common use cases

Cron job heartbeat

Add a curl to the end of your cron job. If the job fails or hangs, the ping never fires and the dead man's switch alerts you.

# crontab -e

0 2 * * * /usr/local/bin/backup.sh && curl -s https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN

Script with output

Capture your script's output and send it for AI classification.

#!/bin/bash

OUTPUT=$(/usr/local/bin/backup.sh 2>&1)

curl -s -X POST \

"https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN" \

-H 'Content-Type: application/json' \

-d "{\"message\": \"$OUTPUT\"}"

Docker container health

Ping from inside a container to confirm it's running.

# docker-compose.yml healthcheck

healthcheck:

test: ['CMD', 'curl', '-sf', 'https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN']

interval: 5m

PowerShell / Windows Task Scheduler

Use Invoke-RestMethod at the end of a scheduled task.

# At the end of your script

Invoke-RestMethod -Uri "https://www.canaryalert.io/api/ping/SOURCE_ID?token=TOKEN"

API reference

GET/api/ping/:source_id?token=:ping_token

Simple heartbeat. Records a SUCCESS event and resets the dead man's switch. Returns 202 Accepted.

POST/api/ping/:source_id?token=:ping_token

Ping with optional message. Without body: same as GET. With {"message": "..."} body: enqueues for AI classification. Returns 202 Accepted.

Error responses

401Missing or invalid token
400Source is paused, or message exceeds 50 KB

Security

Each source gets a unique, randomly generated ping token. The token is separate from your user authentication — it only grants access to ping that specific source. If you suspect a token has been compromised, delete and re-create the source to get a new one.

Tips

  • Use && to only ping on success: ./backup.sh && curl ...
  • Use curl -sf (silent, fail on HTTP errors) to keep logs clean.
  • You can use both email forwarding and HTTP ping on the same source. Either one resets the dead man's switch timer.
  • Set the schedule and grace period on your source to match how often you expect pings.