Heartbeat Monitor

The Heartbeat monitor is a push-based monitor. Instead of Kamustatus checking your service, your service pings Kamustatus at a regular interval. If a ping is not received within the expected window, the monitor is marked as down.

How It Works

1. Create a Heartbeat monitor and get a unique ping URL.
2. Configure your service to send HTTP requests to that URL on a schedule.
3. If Kamustatus does not receive a ping within the expected interval (plus a grace period), it triggers an alert.

The ping URL format is:

https://app.kamustatus.com/ping/<token>

Configuration Options

Option	Description	Default
Name	Display name for the monitor	Required
Interval	Expected time between pings	60s
Grace period	Extra time to wait before marking as down	30s

Sending Pings

Send a GET or POST request to your ping URL. A simple request is enough:

curl https://app.kamustatus.com/ping/<token>

Sending Metrics

You can include a JSON body with custom metrics. The payload must be:

• Maximum 1 KB in size.
• A flat JSON object (no nested objects or arrays).
• Values must be numbers or strings.

curl -X POST https://app.kamustatus.com/ping/<token> \
  -H "Content-Type: application/json" \
  -d '{
    "duration_ms": 1234,
    "records_processed": 500,
    "status": "complete"
  }'

Metrics are stored and can be queried via the API (see heartbeat metrics).

Use Cases

Cron jobs

Ping Kamustatus at the end of a cron job to confirm it ran successfully:

# crontab entry
0 * * * * /usr/local/bin/backup.sh && curl -s https://app.kamustatus.com/ping/<token>

Background workers

Ping after each job processing cycle:

import requests

def process_jobs():
    # ... do work ...
    requests.post("https://app.kamustatus.com/ping/<token>", json={
        "jobs_processed": count,
        "duration_ms": elapsed
    })

CI/CD pipelines

Ping after a successful deployment:

# GitHub Actions example
- name: Notify Kamustatus
  if: success()
  run: curl -s https://app.kamustatus.com/ping/${{ secrets.KAMUPTIME_HEARTBEAT_TOKEN }}

Creating a Heartbeat Monitor via API

curl -X POST https://app.kamustatus.com/api/monitors \
  -H "x-api-key: km_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Backup",
    "type": "heartbeat",
    "interval": 86400,
    "gracePeriod": 3600
  }'

The response includes the pingUrl field with your unique token.