Webhook-Events
Webhooks anlegen, die Events, die kanman für Stories, Runs, Fragen und Teams sendet, Signaturen prüfen sowie die Zustell- und Wiederholungsregeln.
Webhooks schicken eine signierte HTTP-Anfrage an deinen Server, wenn in kanman etwas passiert: Eine Story wird bereit, ein Run endet oder schlägt fehl, eine Frage wartet auf eine Antwort, ein Teambericht erscheint. Damit postest du in deine eigenen Chat-Werkzeuge, aktualisierst ein Dashboard oder startest eigene Automatisierungen.
Webhooks gehören zum Workspace. Owner und Admins legen sie an und verwalten sie; Mitglieder sehen sie nicht.
Webhook anlegen
- Öffne Workspace-Einstellungen > Webhooks (
/<workspace>/settings/webhooks). - Klicke auf Webhook hinzufügen.
- Gib einen Name und die Endpoint-URL deines Servers ein.
- Wähle unter Events, welche Events der Webhook erhalten soll. Sie sind gruppiert nach Stories, Runs und Pull Requests, Entscheidungen sowie Teams und Berichten. Ein neuer Webhook beginnt mit Run abgeschlossen, Run fehlgeschlagen oder gestoppt und Entscheidung wartet.
- Klicke auf Webhook hinzufügen. Abbrechen schließt das Formular, ohne zu speichern.
kanman erzeugt für jeden Webhook ein Signatur-Secret (es beginnt mit whsec_). Dein Empfänger braucht es, um Signaturen zu prüfen. Das Secret steht verdeckt am Webhook; Secret kopieren legt es in die Zwischenablage. Der Schalter an jedem Webhook schaltet die Zustellung ein oder aus.
Alles andere steht im Menü ⋯ des Webhooks:
- Webhook bearbeiten: Name, Endpunkt oder Events ändern. Ein Klick auf den Namen des Webhooks tut dasselbe.
- Test senden: ein
test-Event schicken, siehe Test. - Neu generieren: das Signatur-Secret ersetzen. Es fragt vorher nach: Danach wird jede Anfrage mit dem neuen Secret signiert, und dein Empfänger lehnt sie ab, bis er das neue hat.
- Webhook löschen: fragt vorher nach, siehe unten.
Events
| Event | Gesendet, wenn |
|---|---|
story.created |
Eine Story in einem Team erscheint: Ein Issue wurde aus deinem Tracker übernommen, oder ein freigegebener Story-Entwurf wurde in den Tracker geschrieben. |
story.ready |
Eine Story in die Spalte Bereit des Teams kommt. |
run.started |
kanman mit der Arbeit an einer Story beginnt (auch bei jedem neuen Versuch). |
run.stage_changed |
Ein Run in eine andere Phase wechselt. |
run.completed |
Ein Versuch eines Runs seine Arbeit beendet. |
run.failed |
Ein Versuch fehlschlägt, in ein Zeitlimit läuft oder gestoppt wird. |
pr.opened |
kanman den Pull Request eines Runs öffnet. |
decision.created |
kanman einem Menschen eine Frage stellt. |
decision.resolved |
Jemand eine Frage beantwortet hat, in der App, in Slack, über den MCP-Server oder die REST-API. |
report.published |
Der Wochenbericht eines Teams fertig ist. |
team.paused |
Ein Team pausiert wird. |
team.resumed |
Ein pausiertes Team fortgesetzt wird. |
test |
Du auf Test senden klickst. Nicht abonnierbar. |
Format der Anfrage
Jede Zustellung ist ein HTTP-POST mit JSON-Body:
{
"id": "6f1d2c80-4c1e-4f3a-9b7e-2a1d8c5e9f10",
"event": "run.failed",
"timestamp": "2026-10-01T09:16:56.512Z",
"workspaceId": "a1b2c3d4-0000-4000-8000-000000000001",
"attempt": 1,
"data": {
"team": { "id": "...", "slug": "sandbox-team", "name": "Sandbox Team", "keyPrefix": "SBX" },
"story": {
"id": "...", "key": "SBX-12", "title": "Export invoices as CSV", "readinessScore": 100,
"tracker": { "platform": "github", "key": "#12", "url": "https://github.com/acme/app/issues/12" }
},
"run": {
"key": "run-7f3k", "attempt": 2, "status": "failed", "stage": "verifying", "executor": "claude-code",
"costCents": 140, "budgetCents": 400, "failureClass": "persistent", "prUrl": null, "prNumber": null,
"startedAt": "2026-10-01T09:02:10.000Z", "completedAt": "2026-10-01T09:16:56.000Z"
},
"error": "The coding agent stopped with an error"
}
}
id ist die Zustell-ID; sie bleibt bei Wiederholungen gleich, und attempt zählt die Versuche. timestamp ist der Zeitpunkt des Ereignisses, nicht der Zustellung.
Was data enthält, hängt vom Event ab:
| Events | Felder in data |
|---|---|
story.* |
team, story |
run.* |
team, story, run; run.stage_changed ergänzt previousStage, run.failed ergänzt error |
pr.opened |
team, story, run, pullRequest (url, number) |
decision.* |
team, story, decision (key, title, status, recommendation, options, runKey, resolution, resolvedVia, resolvedBy, resolvedAt, expiresAt); decision.resolved ergänzt result |
report.published |
team, report (periodKey, periodStart, periodEnd, summary, metrics) |
team.* |
team, pausedAt, by |
story ist null bei Events ohne Story, zum Beispiel bei einer Frage zum ganzen Team. Behandle unbekannte Felder als optional: kanman kann Felder ergänzen, entfernt oder benennt sie aber nicht um.
| Header | Beschreibung |
|---|---|
Content-Type |
application/json |
User-Agent |
kanman-webhooks/1 |
X-Kanman-Event |
Event-Typ, zum Beispiel run.failed. |
X-Kanman-Delivery |
Zustell-ID (UUID), dieselbe wie id im Body. Nutze sie, um Duplikate zu ignorieren. |
X-Kanman-Timestamp |
Unix-Zeit in Sekunden, zu der dieser Versuch signiert wurde. |
X-Kanman-Signature |
sha256= gefolgt von der hexadezimalen HMAC-SHA256-Signatur. |
Signatur prüfen
Die Signatur ist HMAC-SHA256 mit deinem Webhook-Secret über den String <X-Kanman-Timestamp>.<roher Request-Body>. Berechne sie über die rohen Bytes, die du empfangen hast, vor jedem JSON-Parsen. Wenn du den Body parst und neu serialisierst, ändern sich Leerzeichen und Schlüsselreihenfolge, und die Signatur passt nicht mehr. Lehne außerdem Zustellungen ab, deren Zeitstempel älter als fünf Minuten ist, damit eine mitgeschnittene Anfrage nicht wiederholt werden kann.
Node.js mit Express:
const crypto = require('crypto')
const express = require('express')
const app = express()
const SECRET = process.env.KANMAN_WEBHOOK_SECRET
// Keep the raw body: the signature covers the exact bytes kanman sent
app.post('/kanman', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Kanman-Timestamp')
const signature = req.get('X-Kanman-Signature') || ''
const expected = 'sha256=' + crypto
.createHmac('sha256', SECRET)
.update(`${timestamp}.${req.body.toString('utf8')}`)
.digest('hex')
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
const valid = signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
if (!fresh || !valid) return res.status(401).send('invalid signature')
const { event, data } = JSON.parse(req.body)
res.status(200).send('ok')
handle(event, data) // do the real work after answering
})
Python mit Flask:
import hashlib
import hmac
import json
import os
import time
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ["KANMAN_WEBHOOK_SECRET"].encode()
@app.post("/kanman")
def kanman_webhook():
timestamp = request.headers.get("X-Kanman-Timestamp", "0")
signature = request.headers.get("X-Kanman-Signature", "")
raw = request.get_data() # raw bytes, not request.json
expected = "sha256=" + hmac.new(SECRET, timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
if abs(time.time() - int(timestamp)) > 300 or not hmac.compare_digest(expected, signature):
return "invalid signature", 401
payload = json.loads(raw)
print(payload["event"], payload["data"])
return "ok", 200
Zustellregeln
- kanman sendet ein Event wenige Sekunden, nachdem es passiert ist.
- Antworte innerhalb von 10 Sekunden mit einem
2xx-Status. Erledige langsame Arbeit erst nach der Antwort. Weiterleitungen werden nicht verfolgt. - Eine fehlgeschlagene Zustellung wird bis zu viermal wiederholt: nach 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden. Netzwerkfehler, Zeitüberschreitungen sowie Antworten mit
408,429und5xxwerden wiederholt; andere4xx-Antworten gelten sofort als endgültiger Fehlschlag. - Nach 5 endgültig fehlgeschlagenen Zustellungen in Folge wird der Webhook pausiert und zeigt Pausiert mit einer kurzen Erklärung; noch wartende Zustellungen für ihn entfallen. Behebe den Endpunkt und schalte den Webhook unter Workspace-Einstellungen > Webhooks mit seinem Schalter wieder ein. Das Einschalten setzt den Fehlerzähler zurück.
- Jedes Event wird mindestens einmal zugestellt. Nutze
X-Kanman-Delivery(oderid), um eine bereits verarbeitete Zustellung zu ignorieren. - Zustellungen verschiedener Events können in anderer Reihenfolge ankommen. Ordne sie über
timestamp.
Test
Wähle im Menü ⋯ eines Webhooks Test senden, um ein test-Event an deinen Endpunkt zu schicken. Die App zeigt an, ob die Zustellung geklappt hat. Der Test-Body sieht so aus:
{
"id": "0b9d4a6e-8c2f-4d1a-9e3b-7f6a5c4d3e2b",
"event": "test",
"timestamp": "2026-10-01T09:00:00.000Z",
"workspaceId": "a1b2c3d4-0000-4000-8000-000000000001",
"attempt": 1,
"data": {
"message": "This is a test delivery from kanman",
"webhookId": "3f0c2b9e-6a51-4c1e-9f0a-2d7b8e41c5aa",
"webhookName": "Ops alerts"
}
}
Ein Test wird einmal gesendet und nicht wiederholt. Für lokale Tests machst du deinen Rechner über einen Tunnel erreichbar und trägst die öffentliche HTTPS-URL als Endpunkt ein.
Um einen Webhook zu löschen, öffne sein Menü ⋯, wähle Webhook löschen und bestätige.
Verwandte Seiten
Zuletzt aktualisiert: January 1, 0001
kanman öffnen