Board-Ereignisse per Webhook senden

Ein Webhook sendet eine signierte HTTPS-Anfrage an Deinen Server, sobald sich auf einem Board etwas ändert: Eine Aufgabe wird angelegt, eine Liste umbenannt, ein Checklisten-Punkt erledigt. Dein Server kann dann ein anderes System aktualisieren, eine Chat-Nachricht posten oder einen Build starten.

Kanroo-Webhooks sind strenger als viele andere. Bevor Kanroo ein Board-Ereignis sendet, muss Dein Endpunkt nachweisen, dass er Dir gehört. Jede Anfrage ist signiert. Ein Webhook stoppt von selbst, wenn Dein Endpunkt immer wieder Fehler liefert oder wenn Du den Zugriff auf das Board verlierst. Diese Seite erklärt jeden Schritt.

Webhooks gibt es in jedem Plan von Kanroo Cloud (siehe Pläne, Preise und Limits). Bei einer selbst gehosteten Installation gibt es sie nur mit der Enterprise Edition.

Was Du brauchst

• Einen öffentlichen HTTPS-Endpunkt auf Port 443. Einfaches HTTP, andere Ports sowie private oder interne Adressen werden nicht akzeptiert. Die URL darf einen Query-String haben, aber keinen Benutzernamen, kein Passwort und kein Fragment.
• Keine Weiterleitungen. Kanroo folgt nie einer Weiterleitung (Redirect). Eine Redirect-Antwort zählt als Fehler.
• Zugriff auf das Board. Du brauchst auf einem aktiven Board mindestens die Rolle „Betrachter“. Archivierte Boards lassen sich nicht auswählen.
• Persönliche Anmeldung. Webhooks sind geschützte persönliche Einstellungen. Melde Dich mit Deiner E-Mail-Adresse und dem Einmalcode an (siehe Persönliche und SSO-Anmeldung). Persönliche API-Schlüssel können keine Webhooks verwalten.

Jeder Webhook gehört nur Dir. Board-Inhaber und Admins der Organisation sehen ihn nicht und können ihn nicht verwalten. Du kannst höchstens fünf Webhooks haben.

Webhook einrichten

Öffne Persönliche Einstellungen über das Kontomenü unten in der Seitenleiste, dann den Tab Webhooks, und wähle Webhook erstellen.

(vergrößern)

1. Gib einen Namen und die Endpunkt-URL ein (Rahmen 1).
2. Wähle das Board (Rahmen 2).
3. Wähle in den Gruppen mindestens ein Ereignis aus (Rahmen 4). Alle auswählen (Rahmen 3) wählt alle Ereignisse, die es heute gibt. Ereignisse, die später dazukommen, werden nie automatisch ausgewählt.
4. Wähle Webhook erstellen (Rahmen 5).

(vergrößern)

1. Kanroo zeigt das Signatur-Secret nur einmal (Rahmen 1). Kopiere es in die Konfiguration Deines Servers. Kanroo kann es nicht noch einmal anzeigen.
2. Bestätige, dass Du es gespeichert hast (Rahmen 2), und wähle Fertig (Rahmen 3).

(vergrößern)

1. Der Webhook zeigt jetzt Verifizierung ausstehend (Rahmen 1). Er sendet noch keine Board-Ereignisse.
2. Bereite Deinen Endpunkt wie im nächsten Abschnitt beschrieben vor. Wähle dann Verifizieren im Menü des Webhooks (⋯, Rahmen 2).

Das Board lässt sich nach dem Anlegen nicht mehr ändern. Um ein anderes Board zu beobachten, legst Du einen zweiten Webhook an.

Endpunkt verifizieren

Mit der Verifizierung weist Du nach, dass der Endpunkt Dir gehört und bereit ist. Kanroo sendet eine Anfrage mit dem Ereignistyp webhook.verification und einer zufälligen Challenge:

{
    "id": "4c8b7d8e-1f0a-4a5e-9a51-7b2f3c9e0d11",
    "type": "webhook.verification",
    "version": 1,
    "occurredAt": "2026-10-04T09:30:00.000Z",
    "organizationId": "…",
    "board": { "id": "…", "name": "Product roadmap" },
    "actor": { "userId": "…", "displayName": "Mira Author" },
    "data": { "challenge": "x8Jq2…" }
}

Dein Endpunkt muss mit Status 2xx und einem JSON-Body antworten, der genau dieselbe Challenge enthält:

{ "challenge": "x8Jq2…" }

Passt die Antwort, wechselt der Webhook auf Aktiv und sendet ab dann Board-Ereignisse. Passt sie nicht, bleibt der Webhook auf Verifizierung ausstehend. Korrigiere den Endpunkt und wähle erneut Verifizieren. Jede Verifizierung nutzt eine neue Challenge und wird nicht automatisch wiederholt. Du kannst einen Webhook höchstens fünfmal pro Stunde verifizieren.

Das Zustellprotokoll (siehe unten) zeigt die Anfrage, die Kanroo gesendet hat, und die Antwort, die zurückkam. Das hilft bei der Fehlersuche.

Signatur prüfen

Jede Anfrage ist nach Standard Webhooks signiert. Sie trägt drei Header:

Header	Inhalt
webhook-id	Die feste ID der Zustellung. Eine Wiederholung oder erneute Zustellung nutzt dieselbe ID.
webhook-timestamp	Der Zeitpunkt dieses Versuchs, in Sekunden seit 1970.
webhook-signature	Eine oder mehrere Signaturen, zum Beispiel v1,K5oZfz…

Nutze eine offizielle Standard-Webhooks-Bibliothek für Deine Programmiersprache und übergib ihr das Secret, das mit whsec_ beginnt. Die Bibliothek prüft die Signatur über die ID, den Zeitstempel und den exakten Roh-Body. Prüfe den Roh-Body so, wie er ankommt. Parse das JSON nicht vorher und serialisiere es nicht neu. Lehne eine Anfrage ab, deren Signatur nicht passt.

Wähle Signaturgeheimnis erneuern im Menü des Webhooks, wenn das Secret nach außen gelangt sein könnte. Kanroo zeigt das neue Secret einmal an. In den nächsten 24 Stunden trägt jede Anfrage Signaturen für das neue und das vorherige Secret. So kannst Du Deinen Server umstellen, ohne Ereignisse zu verlieren. Danach signiert Kanroo nur noch mit dem neuen Secret.

Was eine Anfrage enthält

Jede Anfrage ist ein JSON-POST mit diesen Feldern auf oberster Ebene:

Feld	Inhalt
id	Die ID des Ereignisses. Geht dieselbe Änderung an zwei Deiner Webhooks, hat sie in beiden dieselbe id.
type	Der Ereignistyp, zum Beispiel task.moved
version	Immer 1
occurredAt	Wann die Änderung geschah (UTC)
organizationId	Die Organisation des Boards
board	ID und Name des Boards; ein Seiten-Ereignis hat stattdessen space
actor	Die Person, die die Änderung vorgenommen hat, oder null bei einer Änderung durch Kanroo selbst
data	Das geänderte Objekt, bei Änderungen und Verschiebungen zusätzlich der alte und der neue Wert

Bei einer Änderung über einen persönlichen API-Schlüssel nennt actor den Eigentümer des Schlüssels. Aufgaben aus einem E-Mail-Eingang haben keinen actor und enthalten nie die Adresse des Absenders.

Deduplizieren mit webhook-id. Kanroo stellt jedes Ereignis mindestens einmal zu. In seltenen Fällen kann dieselbe Zustellung doppelt ankommen, etwa bei einem Server-Neustart direkt nach der Antwort Deines Endpunkts. Duplikate erkennst Du am Header webhook-id, nicht an der id im Body.

Reihenfolge. Jeder Webhook sendet eine Anfrage nach der anderen, in der richtigen Reihenfolge. Eine Zustellung, die auf eine Wiederholung wartet, hält spätere Zustellungen desselben Webhooks zurück. Nutze occurredAt und die version des geänderten Objekts, wenn die genaue Reihenfolge wichtig ist.

Schnell antworten

Antworte innerhalb von drei Sekunden mit einem beliebigen 2xx-Status. Erledige die eigentliche Arbeit danach. Kanroo liest höchstens 64 KiB der Antwort und speichert höchstens 4 KiB davon im Zustellprotokoll. Ein Request-Body kann bis zu 1 MiB groß sein.

Wiederholungen

Kanroo versucht bis zu fünfmal, ein Ereignis zuzustellen: sofort, dann nach 1, 5, 15 und 30 Minuten, jeweils mit einer kleinen zufälligen Verzögerung. Ein Retry-After-Header kann eine Wiederholung um höchstens zwei weitere Stunden verzögern.

Antwort Deines Endpunkts	Was Kanroo tut
Beliebiger 2xx	Erfolg
Keine Antwort, Netzwerkfehler oder Timeout	Wiederholung
408, 425, 429 oder beliebiger 5xx	Wiederholung
Beliebige Weiterleitung (3xx)	Abbruch; die Zustellung ist fehlgeschlagen
Jeder andere 4xx	Abbruch nach dem ersten Versuch; die Zustellung ist fehlgeschlagen

Schlägt auch der fünfte Versuch fehl, ist die Zustellung endgültig fehlgeschlagen.

Status

Status	Bedeutung	Was Du tun kannst
Verifizierung ausstehend	Die aktuelle URL ist nicht verifiziert. Es werden keine Board-Ereignisse gesendet.	Verifizieren
Aktiv	Ereignisse werden gesendet.	Test senden, Pausieren, Bearbeiten, Signaturgeheimnis erneuern
Pausiert	Du hast den Webhook gestoppt. Wartende Ereignisse wurden verworfen. Neue Änderungen werden nicht erfasst.	Fortsetzen
Deaktiviert	Kanroo hat den Webhook gestoppt. Den Grund zeigt der Status.	Endpunkt korrigieren, dann Verifizieren
Board-Zugriff entzogen	Du hast den Zugriff auf das Board verloren. Der Webhook lässt sich nicht mehr nutzen.	Löschen

Fahre mit der Maus über einen Status mit Info-Symbol oder setze den Fokus darauf, um den Grund zu lesen. Solange ein Webhook pausiert oder deaktiviert ist, werden Änderungen am Board für ihn nicht erfasst und auch später nicht gesendet.

Warum ein Webhook stoppt

• Drei fehlgeschlagene Zustellungen in Folge. Nach drei endgültig fehlgeschlagenen Zustellungen deaktiviert Kanroo den Webhook und schickt Dir eine E-Mail. Eine erfolgreiche Zustellung setzt den Zähler zurück. Tests, Verifizierungen und erneute Zustellungen zählen nicht.
• Zu viele wartende Zustellungen. Warten 500 Zustellungen für einen Webhook, deaktiviert Kanroo ihn und schickt Dir eine E-Mail.
• Board-Zugriff verloren. Fällt Dein Zugriff auf das Board unter die Rolle „Betrachter“, wechselt der Webhook auf Board-Zugriff entzogen. Er sendet dann nichts mehr, auch wenn Du den Zugriff später zurückbekommst. Du erhältst eine E-Mail. Lösche den Webhook und lege einen neuen an, wenn Du ihn wieder brauchst.
• Alte SSO-Anmeldung. Verlangt Deine Organisation Single Sign-on (SSO), sendet Kanroo eine Zustellung nur, wenn Du Dich in den letzten 24 Stunden per SSO angemeldet hast. Sonst überspringt Kanroo diese Zustellung, und der Webhook bleibt Aktiv. Übersprungene Zustellungen werden nach Deiner Anmeldung nicht nachgeholt. Spätere Ereignisse kommen normal an.
• Das Board wurde gelöscht. Alle Webhooks des Boards werden entfernt, und Du erhältst eine E-Mail.

Ein archiviertes Board behält seine Webhooks. Solange es archiviert ist, sind Änderungen gesperrt. Das Archivieren oder Wiederherstellen eines Boards sendet kein Ereignis.

Um einen Webhook mit Status Deaktiviert wieder zu starten, korrigiere Deinen Endpunkt und wähle Verifizieren. Nach erfolgreicher Verifizierung ist er wieder Aktiv, und der Fehlerzähler beginnt von vorn.

Webhook ändern

• Name und Ereignisse kannst Du jederzeit ändern. Die Änderung gilt nur für neue Ereignisse.
• Eine neue URL musst Du erneut verifizieren. Kanroo verwirft wartende Zustellungen für die alte URL und setzt den Webhook auf Verifizierung ausstehend. Das Secret bleibt gleich.
• Pausieren stoppt den Webhook und verwirft wartende Zustellungen. Fortsetzen startet ihn ohne neue Verifizierung wieder, solange die URL unverändert ist.
• Löschen entfernt den Webhook samt Secret und Zustellprotokoll sofort.

Zustellung testen und prüfen

• Test senden schickt über einen aktiven Webhook eine webhook.test-Anfrage mit leerem data. Sie wird nicht wiederholt und zählt nicht zum Fehlerzähler.
• Zustellprotokoll zeigt standardmäßig die Zustellungen der letzten 14 Tage, die neueste zuerst. Filtere nach Ereignis oder Ergebnis und öffne eine Zeile. Dann siehst Du den genauen Request-Body, jeden Versuch mit seinen Request-Headern, den HTTP-Status und den Anfang der Antwort.
• Erneut zustellen schickt eine Zustellung noch einmal, mit ihrem ursprünglichen Body und ihrer Zustellungs-ID, aber signiert mit dem aktuellen Secret. Das geht für Board-Ereignisse und Tests eines aktiven Webhooks. Die erneute Zustellung wird nicht wiederholt und zählt nicht zum Fehlerzähler.

Verifizierungen, Tests und erneute Zustellungen sind zusammen auf 20 pro Stunde begrenzt, über alle Deine Webhooks hinweg.

Ereignisse

Wähle die Ereignisse, die Du brauchst. Einen Platzhalter für alle gibt es nicht.

Gruppe	Ereignisse
Tasks (Aufgaben)	task.created, task.updated, task.moved, task.deleted, task.archived, task.restored, task.recurred, task.assignee_added, task.assignee_removed, task.label_added, task.label_removed, task.attachment_added, task.attachment_removed
Lists (Listen)	list.created, list.renamed, list.moved, list.work_in_progress_limit_changed, list.color_changed, list.deleted
Comments (Kommentare)	comment.created, comment.updated, comment.deleted
Checklists (Checklisten)	checklist.created, checklist.renamed, checklist.moved, checklist.deleted
Checklist items (Checklisten-Punkte)	checklist.item_added, checklist.item_updated, checklist.item_completed, checklist.item_uncompleted, checklist.item_moved, checklist.item_removed
Pages (Seiten)	page.created, page.updated, page.moved, page.archived, page.restored, page.deleted

Gut zu wissen:

• task.updated deckt Titel, Beschreibung, Priorität und Fälligkeitsdatum ab. Zugewiesene Personen, Labels, Anhänge, Verschiebungen, Kommentare und Checklisten haben eigene Ereignisse.
• Es gibt kein Ereignis „erledigt“ für Aufgaben. Eine Aufgabe ist erledigt, wenn sie in die Erledigt-Liste des Boards wandert. Dabei sendet Kanroo task.moved.
• task.recurred heißt: Kanroo hat eine abgeschlossene wiederkehrende Aufgabe zurückgesetzt. Kanroo hat sie aus der Erledigt-Liste zurück an den Anfang der ersten Liste verschoben und ihr nächstes Fälligkeitsdatum gesetzt. Das Ereignis hat keinen actor.
• Das Löschen einer Liste, Aufgabe oder Checkliste sendet nur ein Ereignis für das gelöschte Objekt, nicht eines für jedes Objekt darin.
• Seiten-Ereignisse gehören zu einem Space, nicht zu einem Board. Ein Webhook erhält sie für alle Spaces in der Organisation seines Boards, die Du sehen kannst.

Wenn etwas nicht funktioniert

Die Verifizierung schlägt immer wieder fehl. Öffne das Zustellprotokoll und die neueste Verifizierung. Prüfe, ob Dein Endpunkt innerhalb von drei Sekunden mit 2xx geantwortet hat, ob er keine Weiterleitung geschickt hat und ob die Antwort JSON mit genau der empfangenen challenge ist.

Meine Signaturprüfung lehnt jede Anfrage ab. Stelle sicher, dass Dein Server den Roh-Body prüft und das vollständige Secret inklusive whsec_ nutzt. Hast Du das Secret erneuert, nutze das neue.

Es kommen keine Ereignisse an. Prüfe, ob der Webhook Aktiv ist, ob die Ereignisse ausgewählt sind und ob die Änderung auf dem ausgewählten Board passiert ist. Ein pausierter oder deaktivierter Webhook erfasst keine Ereignisse.

Der Webhook zeigt „Deaktiviert“. Fahre mit der Maus über den Status. Dort siehst Du, ob Fehlschläge oder zu viele wartende Zustellungen die Ursache waren. Korrigiere den Endpunkt und wähle dann Verifizieren.