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
- Run an endpoint that accepts
POSTon a publichttps://address, port 443, for examplehttps://hooks.customer.example/kymoscope. - In Kymoscope, the project’s Alerts tab, Channels, Add channel: Kind Webhook, a Name, your URL in Address, Add.
- 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.
- Click Send test. Your endpoint gets a message of type
test; answer with any 2xx status and the channel reads Tested. - 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:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Kymoscope-Webhooks/1 |
X-Kymoscope-Event | alert.raised, alert.digest, alert.escalated, runner.lost or test (the body’s type). |
X-Kymoscope-Delivery | The message’s id, the same as the body’s delivery_id. A retry keeps it. |
X-Kymoscope-Signature | t=1792000000,v1=dde4…0c1f: the Unix time it was signed and the signature (below). |
{
"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
| Field | Meaning |
|---|---|
type | alert.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_id | This message’s id: the same on every retry, different for every message. Drop one you have already handled. |
event_id | The episode in the alert history (a digest: its latest episode). null for a test. |
project_id | The project, or null for a personal alert. |
rule | id, name and severity (info, warning or critical). With Hide names in notifications the name is "an alert". All null for a test. |
stream | id and name of the live stream. With Hide names the name is "a stream". null for a test. |
raised_at | When the episode started (ISO 8601, UTC), in the data’s own time. |
cleared_at | When it cleared, or null while it is open. |
count | 1 for alert.raised and alert.escalated; the number of grouped episodes for alert.digest; 0 for a test. |
since | alert.digest: when the first grouped episode started. Otherwise null. |
link | Opens 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.
{
"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.
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)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 arrivedDelivery 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.