Scripting API Reference

Overview

RawMon provides a scripting API via its Cloudflare Worker push relay. Use it to send heartbeat pings from cron jobs, CI/CD pipelines, or custom scripts, and to push custom metrics and alerts.

Heartbeat Endpoints

Each heartbeat monitor gets a unique token. Use these endpoints to report status:

Send a Ping

POST https://rawmon-push-relay.rawops.workers.dev/heartbeat/:token
GET  https://rawmon-push-relay.rawops.workers.dev/heartbeat/:token

A successful ping resets the monitor's grace period timer. If no ping arrives before the grace period expires, the monitor transitions to DOWN and triggers an incident.

Optional body (POST):

{
  "status": "up",
  "message": "Backup completed in 42s",
  "metrics": { "duration": 42, "size_mb": 1024 }
}

Query Status

GET https://rawmon-push-relay.rawops.workers.dev/heartbeat/:token/status

Returns the current heartbeat status, last ping time, and grace period remaining. Useful for external dashboards or health checks.

HMAC-SHA256 Signing

To prevent unauthorized pings, enable HMAC signing on your heartbeat monitor. The app generates a secret key that you include in your scripts.

Signing a Request

#!/bin/bash
TOKEN="your-heartbeat-token"
SECRET="your-hmac-secret"
URL="https://rawmon-push-relay.rawops.workers.dev/heartbeat/$TOKEN"
BODY='{"status":"up","message":"All systems operational"}'

SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | cut -d' ' -f2)

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-RawMon-Signature: sha256=$SIGNATURE" \
  -d "$BODY"

The relay verifies the signature before processing the ping. Requests with an invalid or missing signature are rejected with HTTP 401.

Signing in Python

import hmac, hashlib, json, requests

token = "your-heartbeat-token"
secret = "your-hmac-secret"
url = f"https://rawmon-push-relay.rawops.workers.dev/heartbeat/{token}"
body = json.dumps({"status": "up", "message": "Healthy"})

signature = hmac.new(secret.encode(), body.encode(), hashlib.sha256).hexdigest()

requests.post(url, data=body, headers={
    "Content-Type": "application/json",
    "X-RawMon-Signature": f"sha256={signature}"
})

Cloudflare Workers Template

Deploy a monitoring worker with one click using the public template:

Repository: chalasz/rawmon-monitor-template

The template provides a Cloudflare Worker that checks a list of URLs on a cron schedule and sends heartbeat pings to RawMon. It supports HTTP checks with keyword matching and configurable thresholds.

Custom Webhook Field Mappings

When using the generic webhook source, map fields from any JSON payload to RawMon's expected format using query parameters:

Example URL:

?source=generic&deviceId=ID&titlePath=data.check.name&messagePath=data.check.output&statusPath=data.check.status

Status values interpreted as UP: ok, resolved, up, recovery, healthy. All other values are treated as DOWN.