Webhooks API

Reference for the JSON payload OpsKitty sends to your webhook endpoints.

When a webhook alert is configured and an alert fires or resolves, OpsKitty sends an HTTP POST request to your configured URL with a JSON body. This page documents the payload schema and delivery behavior.

Trigger payload

POST your-webhook-url

{
  "event": "alert.triggered",
  "endpoint": {
    "id": "ep_abc123",
    "name": "Homepage",
    "url": "https://example.com"
  },
  "alert": {
    "id": "al_xyz789",
    "type": "webhook",
    "failure_threshold": 3,
    "description": "See runbook: https://..."
  },
  "triggered_at": "2025-01-15T10:30:00Z",
  "region": "us-east-1",
  "error": "Connection timeout after 30s"
}

Resolved payload

{
  "event": "alert.resolved",
  "endpoint": {
    "id": "ep_abc123",
    "name": "Homepage",
    "url": "https://example.com"
  },
  "alert": {
    "id": "al_xyz789",
    "type": "webhook",
    "failure_threshold": 3
  },
  "triggered_at": "2025-01-15T10:30:00Z",
  "resolved_at": "2025-01-15T10:47:22Z",
  "region": "us-east-1"
}

Delivery requirements

Your endpoint must return HTTP 2xx within 10 seconds.
Non-2xx responses and timeouts are retried up to 3 times with exponential backoff.
The URL must be HTTPS. HTTP-only URLs are rejected.

Verifying the signature

Every request includes an X-OpsKitty-Signature header containing an HMAC-SHA256 signature of the raw request body, computed using your webhook secret. Verify this in your handler to ensure the request genuinely comes from OpsKitty:

const crypto = require('crypto')

function verify(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}