API Reference

Webhook Events.

CheckUpstream sends webhook events to your configured endpoints when things change. All payloads are signed and delivered with retry logic.

HTTP Headers.

Every webhook request includes these headers.

Header	Value	Description
Content-Type	application/json	All webhook payloads are JSON-encoded.
X-Webhook-Signature	sha256=...	HMAC-SHA256 signature of the request body using your webhook secret. Always verify this before processing.
X-Event-Type	<event name>	The event type (e.g., incident.created). Matches the event field in the payload body.

Verifying signatures

Always verify the X-Webhook-Signature header before processing events. The signature is an HMAC-SHA256 hash of the raw request body.

import crypto from "node:crypto";

function verifySignature(body: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (signature.length !== expected.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Event Catalog.

incident.created

Fired when a new incident is detected for a monitored service.

Example payload

{
  "event": "incident.created",
  "timestamp": "2026-04-06T14:32:00Z",
  "data": {
    "id": "inc_abc123",
    "service": "stripe",
    "title": "Stripe API elevated error rates",
    "status": "investigating",
    "severity": "major",
    "started_at": "2026-04-06T14:30:00Z",
    "source": "status_page",
    "url": "https://app.checkupstream.com/incidents/inc_abc123"
  }
}

incident.updated

Fired when an existing incident status changes (e.g., investigating to identified).

Example payload

{
  "event": "incident.updated",
  "timestamp": "2026-04-06T14:45:00Z",
  "data": {
    "id": "inc_abc123",
    "service": "stripe",
    "title": "Stripe API elevated error rates",
    "previous_status": "investigating",
    "status": "identified",
    "severity": "major",
    "update_message": "Root cause identified as database connectivity issue.",
    "url": "https://app.checkupstream.com/incidents/inc_abc123"
  }
}

incident.resolved

Fired when an incident is marked as resolved.

Example payload

{
  "event": "incident.resolved",
  "timestamp": "2026-04-06T15:10:00Z",
  "data": {
    "id": "inc_abc123",
    "service": "stripe",
    "title": "Stripe API elevated error rates",
    "status": "resolved",
    "severity": "major",
    "started_at": "2026-04-06T14:30:00Z",
    "resolved_at": "2026-04-06T15:10:00Z",
    "duration_minutes": 40,
    "url": "https://app.checkupstream.com/incidents/inc_abc123"
  }
}

service.status_changed

Fired when a monitored service transitions between status levels.

Example payload

{
  "event": "service.status_changed",
  "timestamp": "2026-04-06T09:00:00Z",
  "data": {
    "service": "openai",
    "display_name": "OpenAI",
    "previous_status": "operational",
    "status": "degraded_performance",
    "source": "status_page",
    "url": "https://app.checkupstream.com/services/openai"
  }
}

service.degraded

Fired when a service begins experiencing degraded performance.

Example payload

{
  "event": "service.degraded",
  "timestamp": "2026-04-06T11:20:00Z",
  "data": {
    "service": "vercel",
    "display_name": "Vercel",
    "status": "degraded_performance",
    "affected_components": ["Serverless Functions", "Edge Network"],
    "source": "status_page",
    "url": "https://app.checkupstream.com/services/vercel"
  }
}

dependency.risk_changed

Fired when a dependency's risk score changes significantly.

Example payload

{
  "event": "dependency.risk_changed",
  "timestamp": "2026-04-06T08:00:00Z",
  "data": {
    "package": "lodash",
    "ecosystem": "npm",
    "previous_risk": "low",
    "risk": "high",
    "reasons": [
      "No releases in 18 months",
      "3 unpatched CVEs"
    ],
    "url": "https://app.checkupstream.com/dependencies/npm/lodash"
  }
}

alert.triggered

Fired when a configured alert threshold is breached.

Example payload

{
  "event": "alert.triggered",
  "timestamp": "2026-04-06T16:45:00Z",
  "data": {
    "alert_id": "alt_def456",
    "name": "Stripe latency > 2s",
    "service": "stripe",
    "metric": "p99_latency_ms",
    "threshold": 2000,
    "current_value": 3450,
    "project": "my-saas-app",
    "url": "https://app.checkupstream.com/alerts/alt_def456"
  }
}

telemetry.anomaly

Fired when the SDK telemetry pipeline detects anomalous behavior.

Example payload

{
  "event": "telemetry.anomaly",
  "timestamp": "2026-04-06T13:15:00Z",
  "data": {
    "service": "anthropic",
    "anomaly_type": "error_rate_spike",
    "metric": "error_rate",
    "baseline": 0.02,
    "current": 0.15,
    "z_score": 4.2,
    "window_minutes": 5,
    "project": "my-saas-app",
    "url": "https://app.checkupstream.com/telemetry/anomalies"
  }
}

Quick navigation

incident.created incident.updated incident.resolved service.status_changed service.degraded dependency.risk_changed alert.triggered telemetry.anomaly

Ready to receive events?

Configure your webhook endpoint in the dashboard and start receiving real-time notifications.

Go to Dashboard