Webhaken
Webhooks laten externe systemen reageren wanneer werk verandert in Kanera.
Gebruik webhooks wanneer een ander systeem op de hoogte moet zijn van wijzigingen zonder de API voortdurend te ondervragen. Veel voorkomende voorbeelden zijn:
- Update een extern dashboard.
- Synchroniseer gewijzigde kaarten met een ander systeem.
- Implementatie activeren of workflows beoordelen.
- Registreer Kanera-activiteit in een auditsysteem.
Om kaartactiviteit in een teamchatkanaal te posten, heeft u geen eigen webhook nodig. Kanera heeft ingebouwde Chatbestemmingen voor Slack, Discord, Telegram en Zulip die elk bericht voor het platform opmaken. Gebruik een webhook als u de volledige evenementencatalogus, exacte payloads en handtekeningverificatie nodig heeft.
Werkruimtebeheerders kunnen webhookeindpunten maken van Werkruimte-instellingen -> API, in de Aangepaste webhooks sectie. Op zichzelf staande borden hebben hetzelfde API tabblad in hun eigen bordinstellingen. Integraties kunnen ook eindpunten registreren via de openbare API of TypeScript SDK.
Elke webhookbestemming kan alle gebeurtenissen of alleen geselecteerde gebeurtenistypen ontvangen. Vertrekken eventTypes leeg om elke gebeurtenis te ontvangen, of geef een of meer van de onderstaande tekenreeksen voor gebeurtenistypen op.
Plan en machtigingen
- Werkruimtebeheerders kunnen elk generiek webhookeindpunt in die werkruimte zien en beheren.
- Een API-referentie of interactieve OAuth-agent met schrijfmogelijkheid kan een eindpunt registreren zonder beheerdersbevoegdheid wanneer de gebruiker lid is van de werkruimte. Dat eindpunt is gericht op de verbinding die tot stand is gebracht: alleen dezelfde verbindings- en werkruimtebeheerders kunnen het zien of beheren. Met leesreferenties kunnen webhooks niet worden beheerd.
- Webhooks nodig Pro of de 30-dagen Pro-proefversie. Ze zijn niet beschikbaar op gehost Free.
- Op gehost Free wordt het aanmaakformulier vervangen door Webhooks zijn niet beschikbaar in uw abonnement.
Als u de referentie- of agentverbinding intrekt, worden ook de eindpunten met een verbindingsbereik verwijderd. Door de beheerder gemaakte werkruimte-eindpunten blijven behouden totdat een beheerder ze verwijdert.
Wat gebeurt er bij een downgrade
Wanneer een gehoste organisatie overstapt van Pro of een proefversie naar Free, pauzeert Kanera elk ingeschakeld webhook-eindpunt in plaats van iets te verwijderen. Het trekt ook de API-sleutels van de werkruimte in (persoonlijke sleutels blijven werken) en schakelt automatiseringen buiten de Free-limiet uit.
| Op gehost Gratis | Gedrag |
|---|---|
| Bestaande eindpunten | Worden automatisch gepauzeerd en kunnen niet opnieuw worden ingeschakeld zolang de organisatie op Gratis staat. |
| Nieuwe activiteit | Bereikt uw eindpunt niet. |
| Alles wat nog wacht op verzending | Geregistreerd als mislukt webhooks are unavailable on the current plan in plaats van te laat verzonden. |
| Een mislukte levering | Kan niet handmatig opnieuw worden geprobeerd. |
| Configuratie en geschiedenis | Gehouden. Eindpunten, gebeurtenisselecties, geheimen en leveringsgeschiedenis zijn allemaal nog aanwezig. |
Door terug te upgraden naar Pro worden de eindpunten die door de downgrade zijn gepauzeerd opnieuw ingeschakeld en worden de API-sleutels voor de werkruimte hersteld die zijn ingetrokken, zodat een hervatte integratie niet opnieuw hoeft te worden opgebouwd.
Registreer een eindpunt programmatisch
De openbare API maakt dezelfde generieke eindpuntlevenscyclus zichtbaar die wordt gebruikt door de Workspace-instellingen. Elk pad hieronder is relatief ten opzichte van:
/api/v1/workspaces/{workspaceId}/webhooks
| Methode | Pad | Gebruik |
|---|---|---|
GET | (basispad) | Maak een lijst van eindpunten die zichtbaar zijn voor de beller. |
POST | (basispad) | Maak een eindpunt en retourneer het ondertekeningsgeheim één keer. |
PATCH | /{endpointId} | Wijzig de naam, URL, gebeurtenisfilter of ingeschakelde status. |
POST | /{endpointId}/secret | Draai het ondertekeningsgeheim. |
DELETE | /{endpointId} | Verwijder het eindpunt. |
GET | /{endpointId}/deliveries | Lees recente bezorgpogingen. |
POST | /{endpointId}/deliveries/{deliveryId}/retry | Probeer één mislukte bezorging opnieuw. |
Met de TypeScript SDK gebruikt u kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery(), en .delete(). Het geretourneerde eindpunt heeft scope: "workspace" voor een door de beheerder beheerd eindpunt of scope: "connection" wanneer een niet-beheerdersreferentie deze heeft geregistreerd. Bewaar de secret onmiddellijk geretourneerd door creatie of rotatie; later leest, leg het nooit bloot.
Webhook-gebeurtenistypen
De openbare API toont de huidige lijst op:
https://api.kanera.app/webhook-event-types
| Gebied | Soorten evenementen |
|---|---|
| Lijsten | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| Bordscheiders | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| Aangepaste velden | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| Aangepaste veldopties | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| Kaarten | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| Aangepaste velden voor kaarten | card:customFieldValue:set, card:customFieldValue:cleared |
| Kaartlabels en toegewezen personen | card:labels:set, card:assignees:set |
| Kaartbijlagen | card:attachment:created, card:attachment:deleted |
| Controlelijsten voor kaarten | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| Controlelijstitems voor kaarten | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| Etiketten voor werkruimtekaarten | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| Opmerkingen | comment:created, comment:updated, comment:deleted |
| Commentaar reacties | comment:reaction:added, comment:reaction:removed |
| Kaartfeed | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| Borden | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| Bestuursleden | board:member:added, board:member:removed |
| Werkruimtes | workspace:updated, workspace:deleted |
| Leden van de werkruimte | workspace:member:added, workspace:member:updated, workspace:member:removed |
| Gebruikers | user:profile:updated |
| Notities | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| Agent vlucht | agentRun:started, agentRun:updated |
Payload-formaat
Kanera verzendt elke webhook als een JSON-object met een stabiele envelop en gebeurtenisspecifiek data.
| Veld | Betekenis |
|---|---|
id | Unieke webhookgebeurtenis-ID. Dit komt overeen X-Kanera-Event-Id. |
type | Gebeurtenistype, zoals card:created. |
workspaceId | Werkruimte waar de gebeurtenis plaatsvond. |
boardId | Bord waar de gebeurtenis heeft plaatsgevonden, wanneer de gebeurtenis zich op het bord bevindt. |
cardId | Kaart betrokken bij de gebeurtenis, wanneer de payload van de gebeurtenis een kaart identificeert. |
occurredAt | ISO 8601-tijdstempel voor wanneer de gebeurtenis plaatsvond. |
data | Volledige evenementenlading. De vorm hangt ervan af type en komt overeen met de overeenkomstige realtime-gebeurtenispayload. |
Door agenten gerunde evenementen zijn geldig { boardId, cardId, run } binnen data, waar run is de volledige agentrun: its agentName, de userId het werkt voor, status, title, summary, externalUrl, en zijn startedAt, heartbeatAt, en endedAt tijdstempels. agentRun:updated vuurt bij elke hartslag en bij een statuswijziging, dus schakel uw handler in run.status in plaats van elke levering als nieuw werk te behandelen. Een run die het kloppen van de hartslag stopt, wordt beschouwd als één finale agentRun:updated met status: "stalled".
Voorbeeld card:created laadvermogen:
{
"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-levering
Kanera verzendt webhookleveringen als JSON en bevat headers die u kunt gebruiken om het verzoek te verifiëren:
| Koptekst | Betekenis |
|---|---|
X-Kanera-Event-Id | Unieke gebeurtenis-ID. |
X-Kanera-Timestamp | Unix-tijdstempel in seconden. |
X-Kanera-Signature | sha256= plus een HMAC-SHA256-handtekening. |
De handtekening wordt berekend over:
${timestamp}.${rawBody}
met behulp van het webhookeindpuntgeheim.
Webhookleveringen worden opnieuw geprobeerd wanneer het eindpunt een niet-2xx-status retourneert of niet kan worden bereikt. Kanera legt de leveringsgeschiedenis vast, zodat u fouten kunt bekijken, leveringen opnieuw kunt proberen, bestemmingen kunt pauzeren en geheimen kunt roteren vanuit de API-instellingen van de werkruimte.
Controleer webhookhandtekeningen
Controleer de handtekening voordat u de payload vertrouwt.
De Typescript SDK doet dit voor je, en gooit in plaats van een booleaanse waarde terug te geven, zodat een handler niet kan vergeten te controleren:
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);
});
Om het zelf te verifiëren, vergelijkt u de HMAC {timestamp}.{body} in constante tijd. Let op de lengtecontrole: crypto.timingSafeEqual gooit wanneer de twee buffers in lengte verschillen, die een aanvaller controleert.
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);
});
Verifieer altijd aan de hand van de onbewerkte aanvraagtekst. Als uw raamwerk JSON parseert vóór verificatie, kan de handtekeningcontrole mislukken of onbetrouwbaar worden.
Kanera stuurt ook X-Kanera-Timestamp en X-Kanera-Event-Id. Weiger leveringen waarvan de tijdstempel buiten een paar minuten van nu ligt om de herhaling te beperken, en gebruik de gebeurtenis-ID om uw handler idempotent te maken, aangezien leveringen mogelijk opnieuw worden geprobeerd.
Gerelateerde uitgaande opties
Webhooks zijn het pad voor algemene doeleinden. Er bestaan twee beperktere opties voor specifieke doelgroepen:
| Pad | Publiek | Laadvermogen | Waar op te zetten | Abonnement |
|---|---|---|---|---|
| Webhaken | Een ander systeem | JSON ondertekend voor de hele evenementencatalogus | Werkruimte-instellingen -> API | Pro of proef |
| Chatbestemmingen | Een teamkanaal | Opgemaakte berichten voor Slack, Discord, Telegram of Zulip | Werkruimte-instellingen -> Integraties | Pro of proef |
| Persoonlijke bezorgkanalen | Eén persoon | ntfy, Gotify of ondertekende JSON voor uw eigen meldingen | Profielinstellingen -> Meldingen | Pro of proef |
| MCP-evenementabonnementen | De gastheer van een AI-agent | Ondertekende kaart- en commentaargebeurtenissen voor een terugbelactie die door de agent is geverifieerd | De agent abonneert zich via MCP; niets om op te zetten in Kanera | Elk plan |
Chatbestemmingen worden afzonderlijk van webhookeindpunten beheerd en verschijnen niet in de webhooklijst, dus het roteren van een webhookgeheim heeft nooit invloed op een chatbestemming.
Een automatisering Roep een webhook op actie is gericht in plaats van op abonnementsbasis. Het verzendt automation:webhook:called alleen naar het eindpunt dat op de regel is geselecteerd, ongeacht het gewone eindpunt eventTypes filteren, terwijl hetzelfde gedrag voor handtekeningen, nieuwe pogingen en leveringsgeschiedenis behouden blijft. Zie Automatiseringen.