Reference for Keel's webhooks, API, and monitor settings

Webhook alerts

When an incident opens, closes, or a certificate is about to expire, Keel POSTs a JSON payload to each subscribed channel.

Events

• down — incident opened (two consecutive failed checks)
• up — incident closed (a check succeeded after an incident was open)
• cert_expiry — TLS certificate expires within 14 days (fires at most once per 24 hours per monitor)
• test — manual test from the console

Payload

Shape targets Discord-style consumers: content mirrors text for easy Slack/Discord ingestion. Plain JSON — works with Slack, Discord, curl, or any HTTP endpoint.

{
  "event": "down",
  "text": "Keel: example.com is DOWN - timeout (https://example.com/)",
  "content": "Keel: example.com is DOWN - timeout (https://example.com/)",
  "data": {
    "monitor": { "id": "…", "name": "example.com", "url": "https://example.com/", "method": "GET", "expectedStatus": 200, "intervalSeconds": 300, "timeoutMs": 10000, "paused": false, "lastStatus": "down", "failCount": 2, "nextCheckAt": 1727892000000, "createdAt": 1727890800000, "sslExpiresAt": null, "sslIssuer": null, "sslWarnedAt": null },
    "incident": { "id": "…", "monitorId": "…", "openedAt": 1727892000000, "closedAt": null, "reason": "timeout" },
    "check": { "monitorId": "…", "ts": 1727892000000, "status": "down", "statusCode": null, "latencyMs": null, "error": "timeout" },
    "sentAt": 1727892000123
  }
}

Delivery semantics

• One retry on failure (timeout, network error, or non-2xx response)
• 10 second timeout per attempt
• Redirects are not followed — a 3xx response counts as a failed delivery
• HTTPS required for webhook URLs
• Headers: Content-Type: application/json

Quick test with curl

curl -X POST "https://your-webhook.example.com" \
  -H "Content-Type: application/json" \
  -d '{"event":"test","text":"Keel: test alert","content":"Keel: test alert","data":{"monitor":{"name":"test"},"incident":null,"check":null,"sentAt":1234567890}}'

Public API

REST endpoints under /api/v1/ for programmatic access to monitors, checks, incidents, and API tokens.

Authentication

1. Open the console at /app.html and sign in.
2. Create an API token via the API: POST /api/v1/tokens with a session Bearer token. The token is shown once only — copy it immediately.
3. Use it as a Bearer token: Authorization: Bearer keel_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Tokens are prefixed with keel_; session tokens never carry this prefix. API tokens cannot create or list other tokens — use the console session for token management.

Endpoints

Example: list monitors

# Request
curl -H "Authorization: Bearer keel_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  "https://keelmonitor.com/api/v1/monitors"

# Response
{
  "monitors": [
    { "id": "abc123", "name": "Main site", "url": "https://example.com/", "method": "GET", "expectedStatus": 200, "intervalSeconds": 300, "timeoutMs": 10000, "paused": false, "createdAt": "2026-09-01T12:00:00.000Z" }
  ]
}

Example: create a monitor

# Request
curl -X POST "https://keelmonitor.com/api/v1/monitors" \
  -H "Authorization: Bearer keel_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"name":"API health","url":"https://api.example.com/health","method":"GET","expectedStatus":200,"intervalSeconds":60,"timeoutMs":5000}'

# Response
{
  "monitor": {
    "id": "xyz789",
    "name": "API health",
    "url": "https://api.example.com/health",
    "method": "GET",
    "expectedStatus": 200,
    "intervalSeconds": 60,
    "timeoutMs": 5000,
    "paused": false,
    "createdAt": 1768465800000
  }
}