Dokumentace

Kaloko

Stáhnout
Markdown s obrázky (.zip)Složka pro Docusaurus (.zip)Složka pro VitePress (.zip)Složka pro MkDocs (.zip)HTML pro offline čtení (.zip)PDFNovinky jako JSON
Stránky

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žadavekCo dělá
GET /api/v1/orgs/<org>/webhooksVaše webhooky s událostmi, projekty a klíči
POST /api/v1/orgs/<org>/webhooksPř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>/deliveriesPoslední 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álostKdy
run.sharedBěh byl sdílen (nahrán a dokončen)
run.acceptedBěh byl přijat
run.returnedNěkdo vrátil celý běh; s úryvkem jeho poznámky
review.step_changedKrok byl schválen nebo vrácen, nebo rozhodnutí přestalo platit: smazané, vyřešené, nebo odvolané převzaté schválení
comment.addedNový komentář u běhu: vlákno, odpověď nebo vrácený krok s poznámkou
comment.resolvedVlákno je vyřešené, v Kaloku nebo tím, že jeho úkol v Jiře či Linearu je hotový
comment.changedKomentář byl upraven nebo smazán, nebo se vlákno znovu otevřelo (change řekne co)
evidence.readyDoklady běhu nebo releasu jsou připravené ke stažení
health.worseKondice plánovaného běhu nebo běhu z CI je horší než při předchozím průchodu
health.changedSdí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čkaHodnota
Kaloko-EventUdálost, např. comment.added
Kaloko-Signaturet=<unixový čas>,v1=<hex HMAC-SHA256 z "<t>.<tělo>" podpisovým klíčem webhooku>
User-AgentKaloko-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

PoleVýznam
stepId kroku, nebo null u komentáře k celému běhu
locale, viewportSnímek, u kterého komentář vznikl, pokud nějaký je
thread_idPrvní komentář vlákna; u nového vlákna stejné jako comment_id
comment_idKomentář, o kterém událost je
kindcomment, reply nebo returned (poznámka k vrácenému kroku)
changeJen u comment.changed: edited, deleted nebo reopened
authorKdo komentář napsal: email, via a u agentů agent
byKdo ho vyřešil, upravil, smazal nebo znovu otevřel
excerptZačátek komentáře; u smazaného chybí
resolvedJestli je vlákno teď vyřešené
urlVlákno na plachtě
comments_apiVš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.

Na této stránceNa této stránce