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).

Metric Charts

When you send JSON metrics, Kamustatus automatically creates time-series charts on the monitor detail page. Each numeric key gets its own chart with smooth bezier curves. Charts show 6h/24h/72h time ranges with hover tooltips.

Metric Threshold Alerts

Create alerts that trigger when a metric value crosses a threshold. Go to the monitor detail page, scroll to "Threshold Alerts":

• Select a metric key (auto-discovered from your payloads)
• Choose an operator: > < >= <= = !=
• Set a threshold value
• Optionally configure consecutive triggers (e.g., "alert after 3 breaches")

Example: alert when queue_size > 100 or memory_pct >= 95.

API: POST /api/monitors/:id/metric-alerts with { metricKey, operator, threshold, channelId, consecutiveTriggers }

Rate Limiting

Heartbeat pings are rate-limited per plan:

• Free: once per 10 minutes
• Paid plans: based on plan's minimum interval

Returns 429 with retryAfter seconds if rate limited.

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.