Guides

Alert webhooks

Receive alerts as signed JSON on your own HTTPS endpoint: the fields, the headers and how to check the signature.

Set one up

  1. Run an endpoint that accepts POST on a public https:// address, port 443, for example https://hooks.customer.example/kymoscope.
  2. In Kymoscope, the project’s Alerts tab, Channels, Add channel: Kind Webhook, a Name, your URL in Address, Add.
  3. Kymoscope shows the Signing secret once. Copy it into your endpoint’s configuration: it isn’t shown again. Lost it? Delete the channel and add it again.
  4. Click Send test. Your endpoint gets a message of type test; answer with any 2xx status and the channel reads Tested.
  5. Pick the webhook under Notify in the rules that should call it.

The request

One POST per message, with a JSON body and these headers:

HeaderValue
Content-Typeapplication/json
User-AgentKymoscope-Webhooks/1
X-Kymoscope-Eventalert.raised, alert.digest, alert.escalated, runner.lost or test (the body’s type).
X-Kymoscope-DeliveryThe message’s id, the same as the body’s delivery_id. A retry keeps it.
X-Kymoscope-Signaturet=1792000000,v1=dde4…0c1f: the Unix time it was signed and the signature (below).
Body
{
  "type": "alert.raised",
  "delivery_id": "7d3c1f00-0000-4000-8000-0000000000d1",
  "event_id": "7d3c1f00-0000-4000-8000-0000000000e1",
  "project_id": "7d3c1f00-0000-4000-8000-0000000000a1",
  "rule": { "id": "7d3c1f00-0000-4000-8000-0000000000b1", "name": "Oil temperature high", "severity": "critical" },
  "stream": { "id": "7d3c1f00-0000-4000-8000-0000000000c1", "name": "Press 2" },
  "raised_at": "2026-10-26T03:12:07.25+00:00",
  "cleared_at": null,
  "count": 1,
  "since": null,
  "link": "https://app.kymoscope.com/org/…/projects/…?tab=alerts&event=7d3c1f00-0000-4000-8000-0000000000e1"
}

Fields

FieldMeaning
typealert.raised: an episode started. alert.digest: more episodes of the same rule on the same stream, grouped. alert.escalated: a critical episode still active that nobody acknowledged in time (escalation). runner.lost: nobody is watching a stream (below). test: from Send test.
delivery_idThis message’s id: the same on every retry, different for every message. Drop one you have already handled.
event_idThe episode in the alert history (a digest: its latest episode). null for a test.
project_idThe project, or null for a personal alert.
ruleid, name and severity (info, warning or critical). With Hide names in notifications the name is "an alert". All null for a test.
streamid and name of the live stream. With Hide names the name is "a stream". null for a test.
raised_atWhen the episode started (ISO 8601, UTC), in the data’s own time.
cleared_atWhen it cleared, or null while it is open.
count1 for alert.raised and alert.escalated; the number of grouped episodes for alert.digest; 0 for a test.
sincealert.digest: when the first grouped episode started. Otherwise null.
linkOpens the episode in Kymoscope (the people who open it sign in as usual).

Nobody is watching (runner.lost)

When a machine that runs alerts on site hasn’t been heard from for 5 minutes and no other machine runs the same alerts on that stream, each webhook channel of those alerts gets one runner.lost message, at most once an hour per machine and stream. Nothing is sent when it comes back.

Body
{
  "type": "runner.lost",
  "delivery_id": "7d3c1f00-0000-4000-8000-0000000000d2",
  "event_id": null,
  "project_id": "7d3c1f00-0000-4000-8000-0000000000a1",
  "rule": { "id": null, "name": "", "severity": "warning" },
  "stream": { "id": "7d3c1f00-0000-4000-8000-0000000000c1", "name": "Press 2" },
  "raised_at": "2026-11-17T03:12:07.25+00:00",
  "cleared_at": null,
  "count": 3,
  "since": "2026-11-17T03:12:07.25+00:00",
  "link": "https://app.kymoscope.com/org/…/projects/…?tab=alerts",
  "runner_kind": "collector"
}

since (and raised_at) is when the machine was last heard from; count the alerts that stopped running; runner_kind collector or python; link opens the project’s Alerts tab. event_id and the rule’s id are null, its name empty. Hide names replaces the stream’s name as above.

Check the signature

v1 is the hex HMAC-SHA256 of <t>.<raw body>, keyed with the signing secret as text (its UTF-8 bytes, not decoded from hex). Compute it over the body exactly as received, before any JSON parsing, compare in constant time, and refuse a t more than a few minutes from your clock so an old request can’t be replayed. Within those minutes, a copy of a request you already handled has the same delivery_id (part of the signed body): drop it.

Node (node:crypto)
import { createHmac, timingSafeEqual } from 'node:crypto'

// header: the X-Kymoscope-Signature value; body: the raw request body, exactly as received.
function verifyKymoscope(header, body, secret, toleranceS = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=', 2)))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceS) return false
  const expected = createHmac('sha256', secret).update(`${parts.t}.${body}`).digest()
  const got = Buffer.from(parts.v1 ?? '', 'hex')
  return got.length === expected.length && timingSafeEqual(got, expected)
}

// Express: read the body raw, verify, then parse it.
app.post('/kymoscope', express.raw({ type: 'application/json' }), (req, res) => {
  const body = req.body.toString('utf8')
  if (!verifyKymoscope(req.get('X-Kymoscope-Signature') ?? '', body, process.env.KYMOSCOPE_WEBHOOK_SECRET)) {
    return res.sendStatus(401)
  }
  const alert = JSON.parse(body)
  // A repeat (or a replayed copy) has a delivery_id you've already handled: answer 2xx and skip it.
  // Keep the ids of the last 10 minutes at least (here in memory; use your database with several servers).
  if (seen.has(alert.delivery_id)) return res.sendStatus(204)
  seen.set(alert.delivery_id, Date.now())
  console.log(alert.type, alert.rule.name, alert.stream.name, alert.raised_at)
  res.sendStatus(204)
})
const seen = new Map()   // delivery_id -> when it arrived
setInterval(() => { for (const [id, at] of seen) if (Date.now() - at > 600_000) seen.delete(id) }, 60_000)
Python (hmac)
import hashlib, hmac, time

def verify_kymoscope(header: str, body: bytes, secret: str, tolerance_s: int = 300) -> bool:
    """header: the X-Kymoscope-Signature value; body: the raw request body, exactly as received."""
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance_s:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# Flask
@app.post("/kymoscope")
def kymoscope():
    if not verify_kymoscope(request.headers.get("X-Kymoscope-Signature", ""), request.get_data(), SECRET):
        return "", 401
    alert = request.get_json()
    # A repeat (or a replayed copy) has a delivery_id you've already handled: answer 2xx and skip it.
    # Keep the ids of the last 10 minutes at least (here in memory; use your database with several servers).
    now = time.time()
    for k in [k for k, at in seen.items() if now - at > 600]:
        del seen[k]
    if alert["delivery_id"] in seen:
        return "", 204
    seen[alert["delivery_id"]] = now
    print(alert["type"], alert["rule"]["name"], alert["stream"]["name"], alert["raised_at"])
    return "", 204

seen: dict[str, float] = {}  # delivery_id -> when it arrived

Delivery and retries

  • Only public HTTPS endpoints on port 443: no http://, no IP addresses, no names that resolve to a private or local address.
  • No redirects: a 3xx answer counts as a failure. Answer with a 2xx status within 10 seconds; the body of your answer is ignored.
  • A failed message is sent again after about 1, 5, 15, 60 and then every 240 minutes, until it is 24 hours old. Each attempt is signed again with its own t. A test is not retried.
  • A message can arrive more than once: drop repeats by delivery_id.
  • Webhooks follow the same rules as the other channels: one message per episode, repeats grouped into digests. See Notifications.