Skip to main content

Alert on speeding

Scopes: rules:read, rules:write, alerts:read, alerts:write, webhooks:write.

1. Try the rule on past data​

POST /v1/alert-rules:test runs a rule over one device's history without saving it, and says whether and when it would have fired:

curl -s -X POST "https://api.zaitrack.app/v1/alert-rules:test" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"rule\": {\"name\": \"Speeding over 120\", \"kind\": \"speeding\", \"severity\": \"high\",
                \"params\": {\"thresholdKph\": 120, \"minDurationSec\": 30}},
       \"deviceId\": \"$DEVICE_ID\", \"from\": \"2026-10-27T00:00:00Z\", \"to\": \"2026-10-28T00:00:00Z\"}" \
  | jq '{wouldAlert, episodes}'

thresholdKph is 10 to 300. Severities are info, low, medium, high and critical.

2. Save it​

curl -s -X POST "https://api.zaitrack.app/v1/alert-rules" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Speeding over 120", "kind": "speeding", "severity": "high",
       "params": {"thresholdKph": 120, "minDurationSec": 30}}' | jq '{id, enabled}'

A rule is enabled unless you send "enabled": false, and applies to every vehicle unless you list vehicleIds.

3. Receive the alerts​

curl -s -X POST "https://api.zaitrack.app/v1/webhooks" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/zaitrack", "events": ["zaitrack.alert.*"],
       "filters": {"severityAtLeast": "high"}}' | jq '{id, secret}'

Or list the open ones:

curl -s "https://api.zaitrack.app/v1/alerts?status=open&minSeverity=high" \
  -H "Authorization: Bearer $KEY" | jq '.items[] | {id, title, severity, version}'

4. Acknowledge and resolve​

curl -s -X POST "https://api.zaitrack.app/v1/alerts/$ALERT_ID:acknowledge" \
  -H "Authorization: Bearer $KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{"note": "Called the driver"}' | jq '{status, version}'

curl -s -X POST "https://api.zaitrack.app/v1/alerts/$ALERT_ID:resolve" \
  -H "Authorization: Bearer $KEY" \
  -H 'If-Match: "2"' \
  -H "Content-Type: application/json" \
  -d '{"note": "Speed back under the limit"}' | jq '{status, version}'

Send the alert's current version in If-Match. POST /v1/alerts:bulk acknowledges or resolves many at once.