Webhooks

POST /hooks/upbutler HTTP/1.1
Content-Type: application/json
User-Agent: UpButler-Webhooks/2.0 (+https://upbutler.com/docs/webhooks)
webhook-id: evt_0n3q9a12c4r7m1t8wxe
webhook-timestamp: 1791533551
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{
  "id": "evt_0n3q9a12c4r7m1t8wxe",
  "type": "monitor.down",
  "timestamp": "2026-10-09T08:12:31.880Z",
  "workspaceId": "ws_0n3q8jy8r5t1y3u7i9o",
  "data": {
    "monitor": {
      "_id": "mon_0n3q8kz1m4hx7c2v9rt",
      "name": "Search API",
      "kind": "http",
      "state": "down",
      "http": { "url": "https://api.example.com/health", "method": "GET", "expectedStatus": "200-299", ... },
      "tags": ["prod"],
      "url": "https://upbutler.com/app/monitors/mon_0n3q8kz1m4hx7c2v9rt",
      ...
    },
    "check": {
      "_id": "chk_0n3q9a10e9n3p5s7hz2",
      "at": "2026-10-09T08:12:30.911Z",
      "outcome": "down",
      "statusCode": 502,
      "latencyMs": 288,
      "error": "Expected status 200-299, got 502 Bad Gateway",
      "region": "eu-central",
      "hasEvidence": true
    },
    "incident": {
      "id": "inc_0n3q9a11v8k2h5n0qzc",
      "title": "Elevated errors on the Search API",
      "url": "https://upbutler.com/app/incidents/inc_0n3q9a11v8k2h5n0qzc"
    },
    "ai": {
      "analysis": "Since 08:10:44 every check returns HTTP 502 from Cloudflare within ~300ms…",
      "likelyCauses": ["Origin process crashed after deploy"],
      "suggestedActions": ["Check origin process status and recent deploys"],
      "publicSummary": "Some search requests are failing. We're investigating.",
      "severity": "critical",
      ...
    }
  }
}

{
  "id": "evt_0n3q9a19k2m4p6r8t0v",
  "type": "incident.created",
  "timestamp": "2026-10-09T08:12:33.104Z",
  "page": {
    "id": "pg_0n3q8kz0b2fd81mka5e",
    "slug": "acme",
    "name": "Acme Status",
    "url": "https://status.acme.com",
    "status": "major_outage",
    "statusText": "Major outage",
    "api": "https://upbutler.com/api/v1/public/pages/acme"
  },
  "data": {
    "incident": {
      "id": "inc_0n3q9a11v8k2h5n0qzc",
      "kind": "incident",
      "title": "Elevated errors on the Search API",
      "status": "investigating",
      "impact": "critical",
      "startedAt": "2026-10-09T08:12:31.402Z",
      "resolvedAt": null,
      "scheduledStart": null,
      "scheduledEnd": null,
      "components": [{ "componentId": "cmp_0n3q8kz2p7wd4yx0s3a", "status": "major_outage" }],
      "updates": [
        {
          "id": "upd_0n3q9a14w1x3z5b7d9f",
          "status": "investigating",
          "body": "Some search requests are failing. We're investigating and will post an update shortly.",
          "at": "2026-10-09T08:12:31.402Z",
          "ai": true
        }
      ],
      "aiSummary": "Some search requests are failing. We're investigating and will post an update shortly.",
      "url": "https://status.acme.com/incidents/inc_0n3q9a11v8k2h5n0qzc"
    }
  },
  "subscription": {
    "id": "sub_0n3q9b40t2m8w6k1c5v",
    "components": [],
    "manage": "https://upbutler.com/api/v1/public/subscribers/sub_0n3q9b40t2m8w6k1c5v?token=3f9a1c7e2b8d4f6a0c5e9b1d7f3a8c2e6b4d0f9a"
  }
}

{
  "id": "evt_0n3q9a1c3e5g7i9k1m3",
  "type": "component.status_changed",
  "timestamp": "2026-10-09T08:12:32.551Z",
  "page": { "id": "pg_0n3q8kz0b2fd81mka5e", "slug": "acme", ... },
  "data": {
    "component": {
      "id": "cmp_0n3q8kz2p7wd4yx0s3a",
      "key": "search-api",
      "name": "Search API",
      "description": null,
      "group": "grp_0n3q8kz4a1b2c3d4e5f",
      "status": "major_outage",
      "statusMessage": "Expected status 200-299, got 502 Bad Gateway",
      "updatedAt": "2026-10-09T08:12:31.002Z"
    },
    "from": "operational",
    "to": "major_outage"
  },
  "subscription": { ... }
}

import { createHmac, timingSafeEqual } from "node:crypto";

/**
 * Verify a Standard Webhooks signature.
 * rawBody must be the exact bytes received. Don't re-serialize parsed JSON.
 */
export function verifyUpButler(secret: string, headers: Headers, rawBody: string, toleranceSec = 300): boolean {
  const id = headers.get("webhook-id");
  const ts = headers.get("webhook-timestamp");
  const sigHeader = headers.get("webhook-signature");
  if (!id || !ts || !sigHeader) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false; // replay protection

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${ts}.${rawBody}`).digest("base64");

  // The header may carry several space-separated signatures ("v1,abc v1,def").
  return sigHeader.split(" ").some((part) => {
    const [version, sig] = part.split(",");
    if (version !== "v1" || !sig) return false;
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    return a.length === b.length && timingSafeEqual(a, b);
  });
}

import base64, hashlib, hmac, time

def verify_upbutler(secret: str, headers, raw_body: bytes, tolerance_sec: int = 300) -> bool:
    msg_id = headers.get("webhook-id")
    ts = headers.get("webhook-timestamp")
    sig_header = headers.get("webhook-signature")
    if not (msg_id and ts and sig_header):
        return False
    if abs(time.time() - int(ts)) > tolerance_sec:   # replay protection
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for part in sig_header.split(" "):
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

// npm i standardwebhooks
import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.UPBUTLER_WEBHOOK_SECRET!); // the whsec_... value
const event = wh.verify(rawBody, Object.fromEntries(request.headers)); // throws if invalid

# pip install standardwebhooks
from standardwebhooks.webhooks import Webhook
wh = Webhook(os.environ["UPBUTLER_WEBHOOK_SECRET"])  # the whsec_... value
event = wh.verify(raw_body, dict(request.headers))     # raises if invalid

{
  "type": "subscription.verify",
  "timestamp": "2026-10-09T09:00:00.000Z",
  "challenge": "7m2kq9x4c1v8b3n6z0p5w2r",
  "page": { "id": "pg_0n3q8kz0b2fd81mka5e", "name": "Acme Status", "url": "https://status.acme.com" },
  "instructions": "Respond 2xx with the challenge value in the body (plain text or {\"challenge\": \"...\"}) to activate this subscription."
}

// Works in Bun, Deno, Cloudflare Workers, Next.js route handlers… (Request → Response)
import { verifyUpButler } from "./verify";

const seen = new Set<string>(); // use your database or Redis in production

export async function handleUpButler(req: Request): Promise<Response> {
  const raw = await req.text();
  const body = JSON.parse(raw);

  // 1. Subscription handshake: echo the challenge. You don't have the secret yet,
  //    because it is returned by the subscribe call after this succeeds.
  if (body.type === "subscription.verify") {
    return Response.json({ challenge: body.challenge });
  }

  // 2. Everything else must be signed with your subscription's / channel's secret.
  if (!verifyUpButler(process.env.UPBUTLER_WEBHOOK_SECRET!, req.headers, raw)) {
    return new Response("bad signature", { status: 401 });
  }

  // 3. Deduplicate: retries reuse the same webhook-id.
  const id = req.headers.get("webhook-id")!;
  if (seen.has(id)) return new Response(null, { status: 204 });
  seen.add(id);

  // 4. Acknowledge fast, work async (10 s timeout).
  queueMicrotask(() => handleEvent(body));
  return new Response(null, { status: 204 });
}

async function handleEvent(e: any) {
  switch (e.type) {
    case "incident.created":
      console.log(`${e.page.name}: ${e.data.incident.title}`);
      break;
    case "component.status_changed":
      console.log(`${e.data.component.name}: ${e.data.from} → ${e.data.to}`);
      break;
  }
}