Webhooks
Les webhooks permettent aux systèmes externes de réagir lorsque le travail change dans Kanera.
Utilisez des webhooks lorsqu'un autre système doit être informé des modifications sans interroger constamment l'API. Les exemples courants incluent :
- Mettre à jour un tableau de bord externe.
- Synchronisez les cartes modifiées avec un autre système.
- Déclenchez le déploiement ou examinez les workflows.
- Enregistrez l'activité de Kanera dans un système d'audit.
Pour publier une activité de carte dans un canal de discussion d’équipe, vous n’avez pas besoin de votre propre webhook. Kanera a intégré Destinations de discussion pour Slack, Discord, Telegram et Zulip qui formatent chaque message pour la plateforme. Utilisez un webhook lorsque vous avez besoin du catalogue complet d'événements, des charges utiles exactes et de la vérification des signatures.
Les administrateurs de Workspace peuvent créer des points de terminaison de webhook à partir de Paramètres de l'espace de travail -> API, dans le Webhooks personnalisés rubrique. Les cartes autonomes ont le même API dans les paramètres de leur propre tableau. Les intégrations peuvent également enregistrer des points de terminaison via l'API publique ou le SDK TypeScript.
Chaque destination de webhook peut recevoir tous les événements ou uniquement les types d'événements sélectionnés. Partir eventTypes vide pour recevoir tous les événements, ou fournissez une ou plusieurs des chaînes de type d'événement ci-dessous.
Plan et autorisations
- Les administrateurs de l'espace de travail peuvent voir et gérer chaque point de terminaison de webhook générique dans cet espace de travail.
- Un identifiant API compatible en écriture ou un agent OAuth interactif peut enregistrer un point de terminaison sans autorisation d'administrateur lorsque son utilisateur est membre de l'espace de travail. Ce point de terminaison est limité à la connexion en création : seuls les mêmes administrateurs de connexion et d’espace de travail peuvent le voir ou le gérer. Les informations d’identification en lecture ne peuvent pas gérer les webhooks.
- Les webhooks ont besoin Pro ou les 30 jours Essai professionnel. Ils ne sont pas disponibles sur les hébergements Free.
- Sur hébergé Free, le formulaire de création est remplacé par Les webhooks ne sont pas disponibles sur votre forfait.
La révocation des informations d'identification ou de la connexion de l'agent supprime également ses points de terminaison au niveau de la connexion. Les points de terminaison de l'espace de travail créés par l'administrateur restent jusqu'à ce qu'un administrateur les supprime.
Que se passe-t-il en cas de rétrogradation
Lorsqu'une organisation hébergée passe de Pro ou d'un essai à Free, Kanera met en pause chaque point de terminaison de webhook activé plutôt que de supprimer quoi que ce soit. Il révoque également les clés API de l'espace de travail (les clés personnelles continuent de fonctionner) et désactive les automatisations au-delà de la limite gratuite.
| Sur hébergé Gratuit | Comportement |
|---|---|
| Points de terminaison existants | Ils sont automatiquement mis en pause et ne peuvent pas être réactivés lorsque l'organisation est en mode gratuit. |
| Nouvelle activité | N'atteint pas votre point de terminaison. |
| Tout ce qui attend encore d'être envoyé | Enregistré comme échoué avec webhooks are unavailable on the current plan plutôt que d'être envoyé en retard. |
| Une livraison ratée | Ne peut pas être réessayé manuellement. |
| Configuration et historique | Gardé. Les points de terminaison, les sélections d’événements, les secrets et l’historique de livraison sont toujours là. |
La mise à niveau vers Pro réactive les points de terminaison qui ont été suspendus par la rétrogradation et restaure les clés API de l'espace de travail révoquées, de sorte qu'une reprise de l'intégration n'a pas besoin d'être reconstruite.
Enregistrer un point de terminaison par programmation
L'API publique expose le même cycle de vie de point de terminaison générique que celui utilisé par les paramètres Workspace. Chaque chemin ci-dessous est relatif à :
/api/v1/workspaces/{workspaceId}/webhooks
| Méthode | Chemin | Utiliser |
|---|---|---|
GET | (chemin de base) | Répertoriez les points de terminaison visibles par l’appelant. |
POST | (chemin de base) | Créez un point de terminaison et renvoyez son secret de signature une fois. |
PATCH | /{endpointId} | Modifiez son nom, son URL, son filtre d'événements ou son état activé. |
POST | /{endpointId}/secret | Faites pivoter le secret de signature. |
DELETE | /{endpointId} | Supprimez le point de terminaison. |
GET | /{endpointId}/deliveries | Lisez les tentatives de livraison récentes. |
POST | /{endpointId}/deliveries/{deliveryId}/retry | Réessayez une livraison ayant échoué. |
Avec le SDK TypeScript, utilisez kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery(), et .delete(). Le point de terminaison renvoyé a scope: "workspace" pour un point de terminaison géré par un administrateur ou scope: "connection" lorsqu'un identifiant non-administrateur l'a enregistré. Conservez le secret renvoyé par création ou rotation immédiatement ; les lectures ultérieures ne l'exposent jamais.
Types d'événements Webhook
L'API publique expose la liste actuelle à l'adresse :
https://api.kanera.app/webhook-event-types
| Zone | Types d'événements |
|---|---|
| Listes | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| Séparateurs de tableaux | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| Champs personnalisés | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| Options de champ personnalisé | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| Cartes | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| Champs personnalisés de la carte | card:customFieldValue:set, card:customFieldValue:cleared |
| Étiquettes et cessionnaires de cartes | card:labels:set, card:assignees:set |
| Pièces jointes aux cartes | card:attachment:created, card:attachment:deleted |
| Listes de contrôle des cartes | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| Éléments de la liste de contrôle des cartes | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| Étiquettes de cartes d'espace de travail | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| Commentaires | comment:created, comment:updated, comment:deleted |
| Réactions aux commentaires | comment:reaction:added, comment:reaction:removed |
| Flux de cartes | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| Tableaux | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| Membres du tableau | board:member:added, board:member:removed |
| Espaces de travail | workspace:updated, workspace:deleted |
| Membres de l'espace de travail | workspace:member:added, workspace:member:updated, workspace:member:removed |
| Utilisateurs | user:profile:updated |
| Notes | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| L'agent s'exécute | agentRun:started, agentRun:updated |
Format de charge utile
Kanera envoie chaque webhook en tant qu'objet JSON avec une enveloppe stable et spécifique à l'événement data.
| Champ | Signification |
|---|---|
id | Identifiant unique de l’événement webhook. Cela correspond X-Kanera-Event-Id. |
type | Type d'événement, tel que card:created. |
workspaceId | Espace de travail où l'événement s'est produit. |
boardId | Tableau sur lequel l'événement s'est produit, lorsque l'événement est limité au tableau. |
cardId | Carte impliquée dans l'événement, lorsque la charge utile de l'événement identifie une carte. |
occurredAt | Horodatage ISO 8601 indiquant le moment où l'événement s'est produit. |
data | Charge utile complète de l’événement. La forme dépend de type et correspond à la charge utile de l'événement en temps réel correspondant. |
Les événements gérés par les agents sont reportés { boardId, cardId, run } dans data, où run est l'exécution complète de l'agent : son agentName, le userId il agit pour, status, title, summary, externalUrl, et son startedAt, heartbeatAt, et endedAt horodatages. agentRun:updated se déclenche à chaque battement de coeur ainsi qu'à un changement de statut, alors activez votre gestionnaire run.status plutôt que de traiter chaque livraison comme une nouvelle œuvre. Une course qui arrête les battements de cœur arrive en finale agentRun:updated avec status: "stalled".
Exemple card:created charge utile :
{
"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"
}
}
}
Livraison de webhooks
Kanera envoie des livraisons de webhooks au format JSON et inclut des en-têtes que vous pouvez utiliser pour vérifier la demande :
| En-tête | Signification |
|---|---|
X-Kanera-Event-Id | ID d'événement unique. |
X-Kanera-Timestamp | Horodatage Unix en secondes. |
X-Kanera-Signature | sha256= plus une signature HMAC-SHA256. |
La signature est calculée sur :
${timestamp}.${rawBody}
en utilisant le secret du point de terminaison du webhook.
Les livraisons de Webhook sont réessayées lorsque le point de terminaison renvoie un statut non-2xx ou ne peut pas être atteint. Kanera enregistre l'historique des livraisons afin que vous puissiez examiner les échecs, réessayer les livraisons, suspendre les destinations et alterner les secrets à partir des paramètres de l'API de l'espace de travail.
Vérifier les signatures des webhooks
Vérifiez la signature avant de faire confiance à la charge utile.
Le SDK TypeScript fait cela pour vous, et lance plutôt que de renvoyer un booléen afin qu'un gestionnaire ne puisse pas oublier de vérifier :
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);
});
Pour le vérifier vous-même, comparez le HMAC sur {timestamp}.{body} en temps constant. Notez le contrôle de longueur : crypto.timingSafeEqual lance lorsque les deux tampons diffèrent en longueur, ce qu'un attaquant contrôle.
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);
});
Vérifiez toujours par rapport au corps brut de la demande. Si votre framework analyse JSON avant la vérification, la vérification de signature peut échouer ou devenir peu fiable.
Kanera envoie également X-Kanera-Timestamp et X-Kanera-Event-Id. Rejetez les diffusions dont l'horodatage est en dehors de quelques minutes pour une relecture limitée et utilisez l'identifiant d'événement pour rendre votre gestionnaire idempotent, car les diffusions peuvent être réessayées.
Options sortantes associées
Les webhooks sont le chemin à usage général. Deux options plus restreintes existent pour des publics spécifiques :
| Chemin | Public | Charge utile | Où s'installer | Forfait |
|---|---|---|---|---|
| Webhooks | Un autre système | JSON signé sur tout le catalogue d'événements | Paramètres de l'espace de travail -> API | Pro ou essai |
| Destinations de discussion | Un canal d'équipe | Messages formatés pour Slack, Discord, Telegram ou Zulip | Paramètres de l'espace de travail -> Intégrations | Pro ou essai |
| Canaux de livraison personnels | Une personne | ntfy, Gotify ou JSON signé pour vos propres notifications | Paramètres du profil -> Notifications | Pro ou essai |
| Abonnements aux événements MCP | L'hôte d'un agent IA | Carte signée et occurrences de commentaires lors d'un rappel vérifié par l'agent | L'agent s'abonne via MCP ; rien à installer à Kanera | Chaque plan |
Les destinations de discussion sont gérées séparément des points de terminaison des webhooks et n'apparaissent pas dans la liste des webhooks. Par conséquent, la rotation d'un secret de webhook n'affecte jamais une destination de discussion.
Un automatisme Appeler un webhook l’action est ciblée plutôt que basée sur un abonnement. Il envoie automation:webhook:called uniquement au point de terminaison sélectionné sur la règle, quel que soit le point de terminaison ordinaire eventTypes filtrer, tout en conservant le même comportement de signature, de nouvelle tentative et d'historique de livraison. Voir Automatisations.