Webhooks

Webhooks let external systems react when work changes in Kanera.

Use webhooks when another system should know about changes without polling the API constantly. Common examples include:

• Send important card activity to chat.
• Update an external dashboard.
• Sync changed cards to another system.
• Trigger deployment or review workflows.
• Record Kanera activity in an audit system.

Create webhook endpoints from Workspace settings -> API.

Each webhook destination can receive all events or only selected event types. Leave eventTypes empty to receive every event, or provide one or more of the event type strings below.

Webhook event types

The public API exposes the current list at:

https://api.kanera.app/webhook-event-types

For self-hosted installs, open /webhook-event-types on your public API service.

Area	Event types
Lists	list:created, list:updated, list:moved, list:rebalanced, list:deleted
Custom fields	customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted
Custom field options	customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted
Cards	card:created, card:updated, card:moved, card:rebalanced, card:deleted
Card custom fields	card:customFieldValue:set, card:customFieldValue:cleared
Card labels and assignees	card:labels:set, card:assignees:set
Card attachments	card:attachment:created, card:attachment:deleted
Card checklists	card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted
Card checklist items	card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted
Workspace card labels	cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted
Comments	comment:created, comment:updated, comment:deleted
Comment reactions	comment:reaction:added, comment:reaction:removed
Card feed	card:feedItem:created, card:feedItem:updated, card:feedItem:deleted
Boards	board:created, board:updated, board:moved, board:rebalanced, board:deleted
Board members	board:member:added, board:member:removed
Workspaces	workspace:updated, workspace:deleted
Workspace members	workspace:member:added, workspace:member:updated, workspace:member:removed
Users	user:profile:updated
Notes	note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked

Payload format

Kanera sends each webhook as a JSON object with a stable envelope and event-specific data.

Field	Meaning
id	Unique webhook event id. This matches X-Kanera-Event-Id.
type	Event type, such as card:created.
workspaceId	Workspace where the event occurred.
boardId	Board where the event occurred, when the event is board-scoped.
cardId	Card involved in the event, when the event payload identifies a card.
occurredAt	ISO 8601 timestamp for when the event occurred.
data	Full event payload. The shape depends on type and matches the corresponding realtime event payload.

Example card:created payload:

{
  "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 delivery

Kanera sends webhook deliveries as JSON and includes headers you can use to verify the request:

Header	Meaning
X-Kanera-Event-Id	Unique event id.
X-Kanera-Timestamp	Unix timestamp in seconds.
X-Kanera-Signature	sha256= plus an HMAC-SHA256 signature.

The signature is calculated over:

${timestamp}.${rawBody}

using the webhook endpoint secret.

Webhook deliveries are retried when the endpoint returns a non-2xx status or cannot be reached. Kanera records delivery history so you can review failures, retry deliveries, pause destinations, and rotate secrets from the workspace API settings.

Verify webhook signatures

Verify the signature before trusting the payload:

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");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    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);
});

Always verify against the raw request body. If your framework parses JSON before verification, the signature check may fail or become unreliable.