Webhooky
Kaloko umí zavolat vaši adresu, když se s během něco stane: je sdílen, přijat nebo vrácen, krok je schválen nebo vrácen, někdo přidá komentář nebo vyřeší vlákno, doklady jsou připravené nebo se změní kondice. Dokumentace se tak přegeneruje z nejnovějších snímků a portál vašeho QMS ukáže u testovacích případů verdikt a otevřené připomínky, aniž by se musel Kaloka každou minutu ptát. Webhooky jsou součástí plánu Business a vyšších.
Nastavení
Administrátor organizace přidá adresu v Nastavení → Integrace → Webhooky a zaškrtne události a projekty. Každý webhook má vlastní podpisový klíč, který najdete hned u něj. Organizace může mít až 10 webhooků.
Webhook bere všechny otevřené projekty (i běhy bez projektu), nebo jen projekty, které zaškrtnete. Události omezeného projektu dostanou jen webhooky, které ho mají zaškrtnutý, takže portál klienta se dozví o jeho projektu a o ničem jiném. Komentář hosta patří k projektu běhu, na který ho napsal.
Totéž jde přes API s tokenem administrátora:
| Požadavek | Co dělá |
|---|---|
GET /api/v1/orgs/<org>/webhooks | Vaše webhooky s událostmi, projekty a klíči |
POST /api/v1/orgs/<org>/webhooks | Přidá webhook: { "url", "events": [...], "projects": [...], "all_projects": true } |
PATCH /api/v1/orgs/<org>/webhooks/<id> | Změní události nebo projekty; co nepošlete, zůstane |
DELETE /api/v1/orgs/<org>/webhooks/<id> | Odebere ho |
GET /api/v1/orgs/<org>/webhooks/<id>/deliveries | Poslední doručení: událost, stav, pokusy, poslední odpověď |
Prázdný řetězec v projects znamená běhy bez projektu. Bez projects a all_projects bere nový webhook všechny otevřené projekty.
Události
| Událost | Kdy |
|---|---|
run.shared | Běh byl sdílen (nahrán a dokončen) |
run.accepted | Běh byl přijat |
run.returned | Někdo vrátil celý běh; s úryvkem jeho poznámky |
review.step_changed | Krok byl schválen nebo vrácen, nebo rozhodnutí přestalo platit: smazané, vyřešené, nebo odvolané převzaté schválení |
comment.added | Nový komentář u běhu: vlákno, odpověď nebo vrácený krok s poznámkou |
comment.resolved | Vlákno je vyřešené, v Kaloku nebo tím, že jeho úkol v Jiře či Linearu je hotový |
comment.changed | Komentář byl upraven nebo smazán, nebo se vlákno znovu otevřelo (change řekne co) |
evidence.ready | Doklady běhu nebo releasu jsou připravené ke stažení |
health.worse | Kondice plánovaného běhu nebo běhu z CI je horší než při předchozím průchodu |
health.changed | Sdílený běh má v kondici problémy, které jsou oproti běhu před ním nové nebo opravené |
Schválení kroku není komentář, takže přijde jen review.step_changed. Vrácení kroku přinese obojí: rozhodnutí i vlákno, které ho vysvětluje.
Jak doručení vypadá
Každé doručení je JSON POST s těmito hlavičkami:
| Hlavička | Hodnota |
|---|---|
Kaloko-Event | Událost, např. comment.added |
Kaloko-Signature | t=<unixový čas>,v1=<hex HMAC-SHA256 z "<t>.<tělo>" podpisovým klíčem webhooku> |
User-Agent | Kaloko-Webhooks/1 |
Stejné hodnoty posíláme i jako QAwalk-Event a QAwalk-Signature pro příjemce napsané před přejmenováním.
Tělo je obálka kolem data události:
{
"id": "evt_Xb3kQ9vT2mLp",
"type": "comment.added",
"created_at": "2026-10-09T10:14:03.512Z",
"org": "acme",
"data": {
"run": {
"id": "2026-10-09-checkout-a1b2c3",
"scenario": "checkout",
"project": "shop",
"canvas": "https://kaloko.app/acme/runs/2026-10-09-checkout-a1b2c3/",
"api": "https://kaloko.app/api/v1/orgs/acme/runs/2026-10-09-checkout-a1b2c3"
},
"step": "payment",
"locale": "cs",
"viewport": "desktop",
"thread_id": "k3Jd9QpZr",
"comment_id": "k3Jd9QpZr",
"kind": "comment",
"author": { "email": "pavla@acme.example", "via": "session" },
"excerpt": "Po slevovém kódu je celkem 0 Kč. Zeptejte se [email] na pravidlo zaokrouhlení.",
"resolved": false,
"at": "2026-10-09T10:14:03.401Z",
"url": "https://kaloko.app/acme/runs/2026-10-09-checkout-a1b2c3/#step=payment&comments=step&thread=k3Jd9QpZr",
"comments_api": "https://kaloko.app/api/v1/orgs/acme/runs/2026-10-09-checkout-a1b2c3/comments"
}
}
Odpovězte libovolným 2xx do 5 sekund. Kaloko posílá až poté, co odpovědělo člověku, který změnu udělal, takže pomalý příjemce nikoho nezdrží.
Ověření podpisu
Spočítejte HMAC z časového razítka, tečky a těla přesně tak, jak přišlo, porovnejte v konstantním čase a stará razítka odmítněte:
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verify (rawBody, header, secret, toleranceSeconds = 300) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')))
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
}
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, v1 = parts.get("t"), parts.get("v1")
if not t or not v1 or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Opakování
Když vaše adresa neodpoví 2xx, Kaloko to během pár sekund zkusí ještě dvakrát a pak zhruba den v prodlužujících se odstupech (od několika minut po 12 hodin); potom to vzdá. Každý pokus je podepsaný znovu, ale id události zůstává stejné, takže si zpracovaná id pamatujte a opakování přeskočte. Jedna změna nikdy nepřijde jako dvě události: jeden komentář je jeden comment.added.
V Nastavení vidíte poslední odpověď každého webhooku i jeho poslední doručení (doručeno, zkusí se znovu, vzdáno) a API je vypíše pod …/deliveries. Doručení zůstávají v přehledu 30 dní.
Obsah událostí
Události nesou id, stavy, krátké úryvky a odkazy. Snímky, přílohy a celé komentáře zůstávají za API: stáhnete je vlastním tokenem z adres api a comments_api. Úryvek je jeden řádek o nejvýš 140 znacích a e-mailové adresy v něm nahrazuje [email].
Každá událost o běhu má run: id, scenario, project (nebo null), canvas (běh v Kaloku) a api. Časy jsou ve formátu ISO 8601 v UTC. via říká, jak člověk jednal: session (v aplikaci), token (CLI, CI, MCP), agent nebo integration (Jira, Linear).
run.returned
{
"run": { "id": "…", "scenario": "checkout", "project": "shop", "canvas": "…", "api": "…", "environment": "staging", "verdict": "returned" },
"by": { "email": "ada@acme.example", "via": "session" },
"at": "2026-10-09T11:02:41.118Z",
"note": "Celková cena u kroku se slevovým kódem nesedí."
}
review.step_changed
{
"run": { "id": "…", "scenario": "checkout", "project": "shop", "canvas": "…", "api": "…" },
"step": "payment",
"locale": "cs",
"viewport": "desktop",
"state": "returned",
"by": { "email": "ada@acme.example", "via": "session" },
"at": "2026-10-09T10:20:12.006Z",
"comment_id": "Qm2xYt7Lc",
"note": "Celkem ukazuje 0 Kč",
"url": "https://kaloko.app/acme/runs/…/#step=payment",
"review_queue_api": "https://kaloko.app/api/v1/orgs/acme/runs/…/review-queue"
}
state je approved, returned nebo revoked. comment_id určuje rozhodnutí; odvolané převzaté schválení má místo něj "carried": true. locale a viewport přijdou, když rozhodnutí padlo u jednoho snímku. note mají vrácené kroky.
comment.added, comment.resolved, comment.changed
| Pole | Význam |
|---|---|
step | Id kroku, nebo null u komentáře k celému běhu |
locale, viewport | Snímek, u kterého komentář vznikl, pokud nějaký je |
thread_id | První komentář vlákna; u nového vlákna stejné jako comment_id |
comment_id | Komentář, o kterém událost je |
kind | comment, reply nebo returned (poznámka k vrácenému kroku) |
change | Jen u comment.changed: edited, deleted nebo reopened |
author | Kdo komentář napsal: email, via a u agentů agent |
by | Kdo ho vyřešil, upravil, smazal nebo znovu otevřel |
excerpt | Začátek komentáře; u smazaného chybí |
resolved | Jestli je vlákno teď vyřešené |
url | Vlákno na plachtě |
comments_api | Všechny komentáře běhu pro váš token |
url otevře krok s komentáři a vláknem na očích: https://kaloko.app/<org>/runs/<běh>/#step=<krok>&comments=step&thread=<vlákno>. Komentář k celému běhu vede na …/runs/<běh>/#comments=run.
run.shared, run.accepted, evidence.ready, health.worse
run.shared a run.accepted nesou běh s jeho kroky a adresy, kde stáhnete nejnovější snímky a změny od předchozího přijatého běhu (steps_url, changes_url). evidence.ready jmenuje běh nebo release a adresy jeho dokladů, balíčku a matice dohledatelnosti: Doklady o kvalitě pro váš systém kvality. health.worse nese běh, ten předchozí a nové nálezy: Kontrola kondice aplikace.
health.changed
Přijde po každém sdíleném běhu scénáře, jehož kontroly kondice se oproti předchozímu běhu ve stejném prostředí pohnuly: něco selhává (nebo si jím hodnotitel není jistý), co předtím ne, nebo je v pořádku něco, co předtím selhávalo. Počítá se po stránkách, jazycích a kontrolách, takže se hodí na týdenní SEO průchod tisíci stránek. První běh a běh, ve kterém se nic nepohnulo, nepošlou nic.
{
"run": { "id": "2026-10-12-seo-weekly-a1b2c3", "scenario": "seo-weekly", "title": "Týdenní SEO", "environment": "production", "started_at": "2026-10-12T05:00:00.000Z", "canvas": "https://kaloko.app/acme/runs/2026-10-12-seo-weekly-a1b2c3/#health" },
"previous": { "id": "2026-10-05-seo-weekly-d4e5f6", "started_at": "2026-10-05T05:00:00.000Z" },
"counts": { "new": 14, "fixed": 3, "still_open": 120, "unchecked": 0, "worse": 1, "expired": 0 },
"open": 134,
"new": [
{ "id": "eshop|de|HC112|sklep-kubek", "step": "eshop", "locale": "de", "check": "HC112", "text": "The page carries structured data (JSON-LD)", "page": "sklep-kubek", "url": "https://shop.example/de/eshop/kubek", "severity": "warning", "first_seen": { "run": "2026-10-12-seo-weekly-a1b2c3", "at": "2026-10-12T05:00:00.000Z" } }
],
"fixed": [],
"aggregate_url": "https://kaloko.app/api/v1/orgs/acme/runs/2026-10-12-seo-weekly-a1b2c3/health/aggregate",
"diff_url": "https://kaloko.app/api/v1/orgs/acme/runs/2026-10-12-seo-weekly-a1b2c3/health/diff"
}
new a fixed vyjmenují prvních 20, zbytek je za diff_url. Pole vysvětluje API kondice pro dashboardy.