API & Webhooks

Programmatic access to your monitors and real-time event notifications. REST API access requires a Business plan. Outgoing webhooks are available on Pro and above.

Authentication

All REST API requests must include your API key in the Authorization header. Generate a key from Dashboard → API & Webhooks.

curl https://uptraq.io/api/v1/monitors \
  -H "Authorization: Bearer uptraq_live_xxxxxxxxxxxx"

Keep your key secret. It grants full read/write access to your monitors. Rotate it immediately if you suspect it has been leaked.

REST API Endpoints

Base URL: https://uptraq.io/api/v1

GET/monitorsList all monitors

GET /api/v1/monitors

Response 200:
{
  "monitors": [
    {
      "id": "abc123",
      "name": "My API",
      "url": "https://api.example.com/health",
      "status": "up",
      "http_method": "GET",
      "check_interval": 5,
      "is_active": true,
      "last_checked_at": "2025-04-24T10:00:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "response_time_threshold": 2000,
      "keyword_check": null
    }
  ]
}

GET/monitors/:idGet a single monitor

GET /api/v1/monitors/abc123

Response 200: { "monitor": { ... } }
Response 404: { "error": "Monitor not found" }

POST/monitorsCreate a monitor

POST /api/v1/monitors
Content-Type: application/json

{
  "name": "My API",                   // required
  "url": "https://api.example.com",   // required
  "http_method": "GET",               // GET | POST | HEAD | PUT | DELETE
  "check_interval": 5,                // minutes
  "response_time_threshold": 2000,    // ms — optional
  "keyword_check": "ok",              // string to find in body — optional
  "request_headers": { "X-Key": "v" },// optional
  "request_body": "{"ping":1}"      // optional (POST/PUT)
}

Response 201: { "monitor": { "id": "...", ... } }

PATCH/monitors/:idPartial update

PATCH /api/v1/monitors/abc123
Content-Type: application/json

{ "is_active": false }   // pause a monitor

Response 200: { "monitor": { ... } }

DELETE/monitors/:idDelete permanently

DELETE /api/v1/monitors/abc123

Response 204 No Content

Error format

{ "error": "Human-readable message" }

401 — missing or invalid API key

403 — plan does not include API access

404 — monitor not found / not owned by you

400 — validation error

Outgoing Webhooks

Uptraq sends an HTTP POST to your endpoint whenever a monitor changes state. Configure webhook URLs in Dashboard → Notifications → + Add channel → Webhook.

down

Monitor failed (2-region confirmed)

degraded

Response time exceeded threshold

recovered

Monitor returned to healthy state

Payload Format

Every webhook delivery sends this JSON body:

{
  "event":       "down",              // "down" | "degraded" | "recovered"
  "monitorId":   "abc123",
  "monitorName": "My API",
  "monitorUrl":  "https://api.example.com/health",
  "responseTime": 8412,               // ms — null when down
  "error":       "Connection refused",// null when up/recovered
  "timestamp":   "2025-04-24T10:00:00Z"
}

Your endpoint must respond with any 2xx status within 10 seconds. Failed deliveries are not retried automatically — ensure your endpoint is reliable.

Webhook Security (HMAC)

When you set a secret on a webhook channel, Uptraq signs every delivery with HMAC-SHA256. Verify the signature to reject forged requests:

// Node.js example
import crypto from 'crypto'

const sig    = request.headers['x-uptraq-signature'] // hex string
const body   = await request.text()                  // raw body string
const secret = process.env.WEBHOOK_SECRET

const expected = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex')

if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
  return response.status(401).send('Invalid signature')
}

The header is X-Uptraq-Signature. Always use timingSafeEqual to prevent timing attacks.