Webhooks
Mit Webhooks können externe Systeme reagieren, wenn sich die Arbeit in Kanera ändert.
Verwenden Sie Webhooks, wenn ein anderes System über Änderungen informiert werden soll, ohne die API ständig abzufragen. Häufige Beispiele sind:
- Aktualisieren Sie ein externes Dashboard.
- Geänderte Karten mit einem anderen System synchronisieren.
- Lösen Sie Bereitstellungs- oder Überprüfungsworkflows aus.
- Zeichnen Sie die Kanera-Aktivitäten in einem Auditsystem auf.
Um Kartenaktivitäten in einem Team-Chat-Kanal zu posten, benötigen Sie keinen eigenen Webhook. Kanera hat eingebaut Chat-Ziele für Slack, Discord, Telegram und Zulip, die jede Nachricht für die Plattform formatieren. Verwenden Sie einen Webhook, wenn Sie den vollständigen Ereigniskatalog, genaue Nutzlasten und eine Signaturüberprüfung benötigen.
Workspace-Administratoren können Webhook-Endpunkte erstellen Arbeitsbereichseinstellungen -> API, im Benutzerdefinierte Webhooks Abschnitt. Standalone-Boards haben das Gleiche API Registerkarte in ihren eigenen Board-Einstellungen. Integrationen können Endpunkte auch über die öffentliche API oder das TypeScript SDK registrieren.
Jedes Webhook-Ziel kann alle Ereignisse oder nur ausgewählte Ereignistypen empfangen. Geh eventTypes leer, um jedes Ereignis zu empfangen, oder geben Sie eine oder mehrere der folgenden Ereignistypzeichenfolgen an.
Plan und Genehmigungen
- Arbeitsbereichsadministratoren können jeden generischen Webhook-Endpunkt in diesem Arbeitsbereich sehen und verwalten.
- Ein schreibfähiger API-Anmeldedaten- oder interaktiver OAuth-Agent kann einen Endpunkt ohne Administratorberechtigung registrieren, wenn sein Benutzer ein Arbeitsbereichsmitglied ist. Dieser Endpunkt ist auf die erstellende Verbindung beschränkt: Nur die gleichen Verbindungs- und Arbeitsbereichsadministratoren können ihn sehen oder verwalten. Anmeldeinformationen mit Lesebereich können keine Webhooks verwalten.
- Webhooks brauchen Pro oder die 30-Tage Pro-Testversion. Sie sind nicht auf gehosteten Free verfügbar.
- Bei gehosteten kostenlosen Versionen wird das Erstellungsformular durch ersetzt Webhooks sind in Ihrem Plan nicht verfügbar.
Durch das Widerrufen der Anmeldeinformationen oder Agentenverbindung werden auch die verbindungsbezogenen Endpunkte entfernt. Vom Administrator erstellte Arbeitsbereichsendpunkte bleiben bestehen, bis ein Administrator sie löscht.
Was passiert bei einem Downgrade?
Wenn eine gehostete Organisation von Pro oder einer Testversion auf Free umsteigt, pausiert Kanera jeden aktivierten Webhook-Endpunkt, anstatt etwas zu löschen. Es widerruft außerdem Arbeitsbereichs-API-Schlüssel (persönliche Schlüssel funktionieren weiterhin) und deaktiviert Automatisierungen über das kostenlose Limit hinaus.
| Auf gehostetem Free | Verhalten |
|---|---|
| Vorhandene Endpunkte | Wird automatisch angehalten und kann nicht erneut aktiviert werden, während die Organisation im kostenlosen Modus läuft. |
| Neue Aktivität | Erreicht Ihren Endpunkt nicht. |
| Alles, was noch auf den Versand wartet | Als fehlgeschlagen mit aufgezeichnet webhooks are unavailable on the current plan anstatt zu spät zu versenden. |
| Eine fehlgeschlagene Lieferung | Kann nicht manuell wiederholt werden. |
| Konfiguration und Geschichte | Behalten. Endpunkte, Ereignisauswahl, Geheimnisse und Zustellungsverlauf sind alle noch vorhanden. |
Beim Zurück-Upgrade auf Pro werden die Endpunkte, die durch das Downgrade angehalten wurden, wieder aktiviert und die widerrufenen Arbeitsbereich-API-Schlüssel wiederhergestellt, sodass eine wieder aufgenommene Integration nicht neu erstellt werden muss.
Registrieren Sie einen Endpunkt programmgesteuert
Die öffentliche API stellt denselben generischen Endpunkt-Lebenszyklus bereit, der von Workspace-Einstellungen verwendet wird. Jeder untenstehende Pfad ist relativ zu:
/api/v1/workspaces/{workspaceId}/webhooks
| Methode | Pfad | Benutzen |
|---|---|---|
GET | (Basispfad) | Für den Anrufer sichtbare Endpunkte auflisten. |
POST | (Basispfad) | Erstellen Sie einen Endpunkt und geben Sie sein Signaturgeheimnis einmal zurück. |
PATCH | /{endpointId} | Ändern Sie den Namen, die URL, den Ereignisfilter oder den Aktivierungsstatus. |
POST | /{endpointId}/secret | Rotieren Sie das Signaturgeheimnis. |
DELETE | /{endpointId} | Löschen Sie den Endpunkt. |
GET | /{endpointId}/deliveries | Lesen Sie die letzten Zustellversuche. |
POST | /{endpointId}/deliveries/{deliveryId}/retry | Versuchen Sie eine fehlgeschlagene Zustellung erneut. |
Verwenden Sie mit dem TypeScript SDK kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery(), und .delete(). Der zurückgegebene Endpunkt hat scope: "workspace" für einen vom Administrator verwalteten Endpunkt oder scope: "connection" wenn eine Nicht-Administrator-Anmeldeinformation es registriert hat. Speichern Sie die secret wird durch Erstellen oder Drehen sofort zurückgegeben; Spätere Lektüren enthüllen es nie.
Webhook-Ereignistypen
Die öffentliche API stellt die aktuelle Liste unter folgender Adresse bereit:
https://api.kanera.app/webhook-event-types
| Bereich | Veranstaltungstypen |
|---|---|
| Listen | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| Bretttrenner | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| Benutzerdefinierte Felder | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| Benutzerdefinierte Feldoptionen | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| Karten | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| Benutzerdefinierte Kartenfelder | card:customFieldValue:set, card:customFieldValue:cleared |
| Kartenetiketten und Beauftragte | card:labels:set, card:assignees:set |
| Kartenanhänge | card:attachment:created, card:attachment:deleted |
| Karten-Checklisten | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| Elemente der Kartencheckliste | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| Etiketten für Arbeitsplatzkarten | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| Kommentare | comment:created, comment:updated, comment:deleted |
| Kommentarreaktionen | comment:reaction:added, comment:reaction:removed |
| Karteneinzug | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| Boards | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| Vorstandsmitglieder | board:member:added, board:member:removed |
| Arbeitsbereiche | workspace:updated, workspace:deleted |
| Mitglieder des Arbeitsbereichs | workspace:member:added, workspace:member:updated, workspace:member:removed |
| Benutzer | user:profile:updated |
| Notizen | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| Agent läuft | agentRun:started, agentRun:updated |
Nutzlastformat
Kanera sendet jeden Webhook als JSON-Objekt mit stabilem Umschlag und ereignisspezifisch data.
| Feld | Bedeutung |
|---|---|
id | Eindeutige Webhook-Ereignis-ID. Das passt X-Kanera-Event-Id. |
type | Ereignistyp, z. B card:created. |
workspaceId | Arbeitsbereich, in dem das Ereignis aufgetreten ist. |
boardId | Board, auf dem das Ereignis stattgefunden hat, wenn das Ereignis auf das Board beschränkt ist. |
cardId | Am Ereignis beteiligte Karte, wenn die Ereignisnutzlast eine Karte identifiziert. |
occurredAt | ISO 8601-Zeitstempel für das Auftreten des Ereignisses. |
data | Vollständige Event-Nutzlast. Die Form hängt davon ab type und stimmt mit der entsprechenden Echtzeit-Ereignisnutzlast überein. |
Von Agenten ausgeführte Ereignisse werden übertragen { boardId, cardId, run } in data, wo run ist der vollständige Agentenlauf: its agentName, die userId es wirkt für, status, title, summary, externalUrl, und es ist startedAt, heartbeatAt, und endedAt Zeitstempel. agentRun:updated Wird bei jedem Herzschlag sowie bei einer Statusänderung ausgelöst, also schalten Sie Ihren Handler ein run.status anstatt jede Lieferung als neue Arbeit zu behandeln. Ein Lauf, der den Herzschlag zum Stillstand bringt, ist ein Finale agentRun:updated mit status: "stalled".
Beispiel card:created Nutzlast:
{
"id": "7e5c982a-e6c9-4ea7-9647-b14fe73ed50a",
"type": "card:created",
"workspaceId": "a069fd45-3bb3-4928-bac9-cb574a050d20",
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"cardId": "70c39cef-1aec-44e6-a8f5-f36f765a818d",
"occurredAt": "2026-05-28T12:34:56.000Z",
"data": {
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"card": {
"id": "70c39cef-1aec-44e6-a8f5-f36f765a818d",
"boardId": "48a52a55-763e-4c64-8a76-51ac56247f5c",
"listId": "3bb3c1b3-8fc7-4807-854d-2d5ff62df147",
"title": "Prepare kickoff agenda",
"position": "1000.0000000000"
}
}
}
Webhook-Zustellung
Kanera sendet Webhook-Lieferungen als JSON und enthält Header, die Sie zur Überprüfung der Anfrage verwenden können:
| Kopfzeile | Bedeutung |
|---|---|
X-Kanera-Event-Id | Eindeutige Ereignis-ID. |
X-Kanera-Timestamp | Unix-Zeitstempel in Sekunden. |
X-Kanera-Signature | sha256= plus eine HMAC-SHA256-Signatur. |
Die Signatur wird berechnet über:
${timestamp}.${rawBody}
Verwenden des Webhook-Endpunktgeheimnisses.
Webhook-Zustellungen werden wiederholt, wenn der Endpunkt einen Nicht-2xx-Status zurückgibt oder nicht erreichbar ist. Kanera zeichnet den Lieferverlauf auf, sodass Sie Fehler überprüfen, Lieferungen wiederholen, Ziele pausieren und Geheimnisse aus den Workspace-API-Einstellungen rotieren können.
Webhook-Signaturen überprüfen
Überprüfen Sie die Signatur, bevor Sie der Nutzlast vertrauen.
Die TypeScript-SDK erledigt dies für Sie und gibt einen booleschen Wert aus, anstatt ihn zurückzugeben, damit ein Handler nicht vergessen kann, Folgendes zu überprüfen:
import { parseWebhook } from "@kanera/sdk";
app.post("/kanera/webhook", express.raw({ type: "application/json" }), async (req, res) => {
const event = await parseWebhook({
secret: process.env.KANERA_WEBHOOK_SECRET!,
payload: req.body, // the raw bytes
headers: req.headers,
});
// Handle event.type, event.workspaceId, event.boardId, event.cardId, and event.data.
res.sendStatus(204);
});
Um es selbst zu überprüfen, vergleichen Sie den HMAC {timestamp}.{body} in konstanter Zeit. Beachten Sie die Längenprüfung: crypto.timingSafeEqual wirft, wenn die beiden Puffer unterschiedliche Längen haben, die ein Angreifer kontrolliert.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/kanera/webhook", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.header("X-Kanera-Timestamp") ?? "";
const signature = req.header("X-Kanera-Signature") ?? "";
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.KANERA_WEBHOOK_SECRET!)
.update(`${timestamp}.${req.body.toString("utf8")}`)
.digest("hex");
const received = Buffer.from(signature);
const digest = Buffer.from(expected);
if (received.length !== digest.length || !crypto.timingSafeEqual(received, digest)) {
return res.status(401).send("invalid signature");
}
const event = JSON.parse(req.body.toString("utf8"));
// Handle event.type, event.workspaceId, event.boardId, event.cardId, and event.data.
res.sendStatus(204);
});
Überprüfen Sie immer anhand des rohen Anforderungstexts. Wenn Ihr Framework JSON vor der Überprüfung analysiert, schlägt die Signaturprüfung möglicherweise fehl oder wird unzuverlässig.
Kanera sendet auch X-Kanera-Timestamp und X-Kanera-Event-Id. Lehnen Sie Lieferungen ab, deren Zeitstempel außerhalb einiger Minuten liegt, um die Wiedergabe zu binden, und verwenden Sie die Ereignis-ID, um Ihren Handler idempotent zu machen, da Lieferungen möglicherweise wiederholt werden.
Verwandte Outbound-Optionen
Webhooks sind der Allzweckpfad. Für bestimmte Zielgruppen gibt es zwei engere Optionen:
| Pfad | Publikum | Nutzlast | Wo einzurichten | Tarif |
|---|---|---|---|---|
| Webhooks | Ein anderes System | Signiertes JSON im gesamten Veranstaltungskatalog | Arbeitsbereichseinstellungen -> API | Pro oder Testversion |
| Chatziele | Ein Teamkanal | Formatierte Nachrichten für Slack, Discord, Telegram oder Zulip | Arbeitsbereichseinstellungen -> Integrationen | Pro oder Testversion |
| Persönliche Lieferkanäle | Eine Person | ntfy, Gotify oder signiertes JSON für Ihre eigenen Benachrichtigungen | Profileinstellungen -> Benachrichtigungen | Pro oder Testversion |
| MCP-Veranstaltungsabonnements | Der Gastgeber eines KI-Agenten | Signierte Karten- und Kommentarvorkommnisse zu einem Rückruf, den der Agent überprüft hat | Der Agent abonniert über MCP; In Kanera gibt es nichts einzurichten | Jeder Plan |
Chat-Ziele werden getrennt von Webhook-Endpunkten verwaltet und erscheinen nicht in der Webhook-Liste, sodass sich die Rotation eines Webhook-Geheimnisses nie auf ein Chat-Ziel auswirkt.
Eine Automatisierung Rufen Sie einen Webhook auf Die Aktion ist zielgerichtet und nicht abonnementbasiert. Es sendet automation:webhook:called nur für den in der Regel ausgewählten Endpunkt, unabhängig vom Normalwert dieses Endpunkts eventTypes Filtern, wobei Signatur, Wiederholungsversuche und Zustellungsverlaufsverhalten beibehalten werden. Siehe Automatisierungen.