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.

Webhooks in den Workspace-Einstellungen (Desktop) Webhooks in den Workspace-Einstellungen (Mobile)

Webhook anlegen

  1. Öffne Workspace-Einstellungen > Webhooks (/<workspace>/settings/webhooks).
  2. Klicke auf Webhook hinzufügen.
  3. Gib einen Name und die Endpoint-URL deines Servers ein.
  4. 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.
  5. Klicke auf Webhook hinzufügen. Abbrechen schließt das Formular, ohne zu speichern.
Formular zum Anlegen eines Webhooks (Desktop) Formular zum Anlegen eines Webhooks (Mobile)

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, 429 und 5xx werden wiederholt; andere 4xx-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 (oder id), 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.

Bestätigungsdialog zum Löschen eines Webhooks (Desktop) Bestätigungsdialog zum Löschen eines Webhooks (Mobile)

Verwandte Seiten

Zuletzt aktualisiert: January 1, 0001

kanman öffnen