Team-Webhooks | kanman Dokumentation

Mit einem Team-Webhook teilt ein anderes System kanman mit, dass etwas passiert ist: ein Alarm aus dem Monitoring, ein fehlgeschlagenes Release, ein Formular, das ein Kunde ausgefüllt hat, eine Nachricht aus Ihren eigenen Werkzeugen. Jeder Absender bekommt seine eigene URL und sein eigenes Geheimnis. kanman liest, was ankommt, entscheidet, was es für das Team bedeutet, und handelt wie bei jeder anderen Anfrage: Es schreibt vielleicht eine Story, ergänzt eine bestehende, fragt jemanden oder lässt es auf sich beruhen.

Was eine Zustellung sagt, gilt nie als Anweisung. kanman behandelt es als Information von außerhalb des Teams.

Um Arbeit stattdessen aus einem Skript mit bekanntem Titel und bekannter Beschreibung zu starten, nutzen Sie die Story-Endpunkte der REST-API.

Einen Webhook anlegen

Sie brauchen dafür die Rolle Inhaber oder Admin im Workspace.

Öffnen Sie das Team, dann Team > API und Webhooks (/<workspace>/teams/<team>/team/api).
Klicken Sie auf Webhook hinzufügen, geben Sie ihm den Namen des Absenders, zum Beispiel „Grafana“ oder „Release-Pipeline“, und klicken Sie auf Erstellen.
Kopieren Sie die Webhook-URL und das Signaturgeheimnis. Das Geheimnis wird nur einmal angezeigt. kanman speichert es verschlüsselt und zeigt es nie wieder an.

Neues Geheimnis ersetzt das Geheimnis: Das alte gilt sofort nicht mehr, die URL bleibt. Widerrufen schaltet den Webhook endgültig ab; seine URL antwortet danach mit 410.

Mitglieder des Workspace sehen die Webhooks und ihre letzten Zustellungen, können sie aber nicht ändern.

Eine Zustellung signieren

Senden Sie einen POST an die Webhook-URL mit diesen drei Headern:

Header	Wert
`X-Kanman-Timestamp`	Die aktuelle Zeit in Unix-Sekunden.
`X-Kanman-Nonce`	Ein Wert, den Sie nur einmal verwenden, 8 bis 128 Buchstaben, Ziffern, `.`, `:`, `-` oder `_`, zum Beispiel eine UUID.
`X-Kanman-Signature`	`sha256=` gefolgt vom hexadezimalen HMAC-SHA256 von `<timestamp>.<nonce>.<body>`, mit dem Signaturgeheimnis als Schlüssel.

Der Body kann beliebiger Text bis 256 KB sein; JSON eignet sich am besten. kanman liest davon bis zu 8.000 Zeichen.

SECRET="kmw_..."            # das Signaturgeheimnis
URL="https://api.kanman.ai/functions/v1/team-webhook/..."
BODY='{"alert":"Fehlerquote im Checkout über 5 %","service":"checkout","since":"2026-10-19T09:12:00Z"}'
TS=$(date +%s)
NONCE=$(uuidgen)
SIG=$(printf '%s.%s.%s' "$TS" "$NONCE" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')

curl "$URL" \
  --header "Content-Type: application/json" \
  --header "X-Kanman-Timestamp: $TS" \
  --header "X-Kanman-Nonce: $NONCE" \
  --header "X-Kanman-Signature: sha256=$SIG" \
  --data "$BODY"

Antworten

Status	`outcome`	Bedeutung
`202`	`accepted`	kanman hat die Zustellung und sieht sie sich an.
`400`	`invalid`	Ein Header fehlt oder ist ungültig.
`401`	`bad_signature`	Die Signatur passt nicht zu Body, Nonce und Zeitstempel.
`401`	`stale`	Der Zeitstempel liegt mehr als fünf Minuten neben kanmans Uhr.
`409`	`replay`	Diese Nonce wurde schon verwendet. Senden Sie mit jeder Zustellung eine neue.
`409`	`not_on_kanman`	kanman betreut dieses Team noch nicht.
`413`	`too_large`	Der Body ist größer als 256 KB.
`429`	`rate_limited`	Mehr als 30 Zustellungen in einer Minute. Warten Sie die Sekunden aus `Retry-After` ab.
`404`, `410`		Die URL ist unbekannt, oder der Webhook wurde widerrufen.

Jede Antwort ist JSON mit der Kennung der Zustellung: { "delivery": "…", "outcome": "accepted" }. Die Karte des Webhooks unter Team > API und Webhooks listet seine letzten fünf Zustellungen mit ihrem Ergebnis.