Webhooks
Os webhooks permitem que sistemas externos reajam quando o trabalho muda no Kanera.
Use webhooks quando outro sistema precisar saber sobre alterações sem consultar a API constantemente. Exemplos comuns incluem:
- Atualize um painel externo.
- Sincronize os cartões alterados para outro sistema.
- Acione a implantação ou revise fluxos de trabalho.
- Registre a atividade do Kanera em um sistema de auditoria.
Para postar atividades de cartão em um canal de bate-papo da equipe, você não precisa de seu próprio webhook. Kanera tem embutido Destinos de bate-papo para Slack, Discord, Telegram e Zulip que formatam cada mensagem para a plataforma. Use um webhook quando precisar do catálogo completo de eventos, cargas exatas e verificação de assinatura.
Os administradores do workspace podem criar endpoints de webhook a partir de Configurações do espaço de trabalho -> API, no Webhooks personalizados seção. quadros independentes têm o mesmo API guia em suas próprias configurações do quadro. As integrações também podem registrar endpoints por meio da API pública ou do SDK TypeScript.
Cada destino de webhook pode receber todos os eventos ou apenas tipos de eventos selecionados. Sair eventTypes vazio para receber todos os eventos ou forneça uma ou mais das strings de tipo de evento abaixo.
Plano e permissões
- Os administradores do espaço de trabalho podem ver e gerenciar todos os endpoints genéricos do webhook nesse espaço de trabalho.
- Uma credencial de API com capacidade de gravação ou um agente OAuth interativo pode registrar um terminal sem autoridade administrativa quando seu usuário for um membro do espaço de trabalho. Esse ponto de extremidade tem como escopo a conexão de criação: somente a mesma conexão e os administradores do espaço de trabalho podem vê-lo ou gerenciá-lo. As credenciais com escopo de leitura não podem gerenciar webhooks.
- Necessidade de webhooks Pro ou os 30 dias Avaliação profissional. Eles não estão disponíveis em hospedagem gratuita.
- No hospedado gratuitamente, o formulário de criação é substituído por Webhooks não estão disponíveis no seu plano.
A revogação da credencial ou da conexão do agente também remove seus pontos de extremidade com escopo de conexão. Os pontos de extremidade do workspace criados pelo administrador permanecem até que um administrador os exclua.
O que acontece em um downgrade
Quando uma organização hospedada muda de Pro ou de avaliação para Gratuito, Kanera pausa todos os endpoints de webhook habilitados em vez de excluir qualquer coisa. Ele também revoga as chaves de API do espaço de trabalho (as chaves pessoais continuam funcionando) e desativa as automações além do limite Gratuito.
| Em hospedagem gratuita | Comportamento |
|---|---|
| Pontos de extremidade existentes | Pausados automaticamente e não podem ser reativados enquanto a organização estiver no modo Gratuito. |
| Nova atividade | Não atinge seu endpoint. |
| Qualquer coisa ainda esperando para enviar | Registrado como falhou com webhooks are unavailable on the current plan em vez de enviado com atraso. |
| Uma entrega falhada | Não é possível tentar novamente manualmente. |
| Configuração e histórico | Mantido. Endpoints, seleções de eventos, segredos e histórico de entrega ainda estão lá. |
A atualização de volta para o Pro reativa os endpoints que foram pausados pelo downgrade e restaura as chaves de API do espaço de trabalho que ele revogou, portanto, uma integração retomada não precisa ser reconstruída.
Registrar um endpoint programaticamente
A API pública expõe o mesmo ciclo de vida do endpoint genérico usado pelas configurações do Workspace. Cada caminho abaixo é relativo a:
/api/v1/workspaces/{workspaceId}/webhooks
| Método | Caminho | Usar |
|---|---|---|
GET | (caminho base) | Lista os pontos de extremidade visíveis para o chamador. |
POST | (caminho base) | Crie um endpoint e retorne seu segredo de assinatura uma vez. |
PATCH | /{endpointId} | Altere seu nome, URL, filtro de eventos ou estado ativado. |
POST | /{endpointId}/secret | Gire o segredo de assinatura. |
DELETE | /{endpointId} | Exclua o ponto de extremidade. |
GET | /{endpointId}/deliveries | Leia as tentativas de entrega recentes. |
POST | /{endpointId}/deliveries/{deliveryId}/retry | Tente novamente uma entrega com falha. |
Com o SDK TypeScript, use kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery()e .delete(). O endpoint retornado tem scope: "workspace" para um endpoint gerenciado pelo administrador ou scope: "connection" quando uma credencial não administrativa a registrou. Armazene o secret retornado por criação ou rotação imediatamente; leituras posteriores nunca o expõem.
Tipos de eventos de webhook
A API pública expõe a lista atual em:
https://api.kanera.app/webhook-event-types
| Área | Tipos de eventos |
|---|---|
| Listas | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| Separadores de quadro | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| Campos personalizados | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| Opções de campo personalizado | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| Cartões | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| Campos personalizados do cartão | card:customFieldValue:set, card:customFieldValue:cleared |
| Etiquetas e destinatários dos cartões | card:labels:set, card:assignees:set |
| Anexos de cartão | card:attachment:created, card:attachment:deleted |
| Listas de verificação de cartão | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| Itens da lista de verificação do cartão | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| Etiquetas de cartão de espaço de trabalho | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| Comentários | comment:created, comment:updated, comment:deleted |
| Reações de comentários | comment:reaction:added, comment:reaction:removed |
| Alimentação de cartão | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| Quadros | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| Membros do quadro | board:member:added, board:member:removed |
| Espaços de trabalho | workspace:updated, workspace:deleted |
| Membros do espaço de trabalho | workspace:member:added, workspace:member:updated, workspace:member:removed |
| Usuários | user:profile:updated |
| Notas | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| Execuções do agente | agentRun:started, agentRun:updated |
Formato de carga útil
Kanera envia cada webhook como um objeto JSON com um envelope estável e específico do evento data.
| Campo | Significado |
|---|---|
id | ID de evento de webhook exclusivo. Isso corresponde X-Kanera-Event-Id. |
type | Tipo de evento, como card:created. |
workspaceId | Espaço de trabalho onde o evento ocorreu. |
boardId | Quadro onde o evento ocorreu, quando o evento está no escopo do quadro. |
cardId | Cartão envolvido no evento, quando o payload do evento identifica um cartão. |
occurredAt | Carimbo de data/hora ISO 8601 para quando o evento ocorreu. |
data | Carga útil completa do evento. A forma depende type e corresponde à carga útil do evento em tempo real correspondente. |
Os eventos executados pelo agente são transportados { boardId, cardId, run } em data, onde run é a execução completa do agente: é agentName, o userId atua para, status, title, summary, externalUrl, e seu startedAt, heartbeatAte endedAt carimbos de data/hora. agentRun:updated dispara a cada pulsação, bem como a uma mudança de status, então ative seu manipulador run.status em vez de tratar cada entrega como um novo trabalho. Uma corrida que para de bater o coração chega como uma final agentRun:updated com status: "stalled".
Exemplo card:created carga útil:
{
"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"
}
}
}
Entrega de webhook
Kanera envia entregas de webhook como JSON e inclui cabeçalhos que você pode usar para verificar a solicitação:
| Cabeçalho | Significado |
|---|---|
X-Kanera-Event-Id | ID de evento exclusivo. |
X-Kanera-Timestamp | Carimbo de data/hora Unix em segundos. |
X-Kanera-Signature | sha256= além de uma assinatura HMAC-SHA256. |
A assinatura é calculada sobre:
${timestamp}.${rawBody}
usando o segredo do endpoint do webhook.
As entregas de webhook são repetidas quando o endpoint retorna um status diferente de 2xx ou não pode ser alcançado. Kanera registra o histórico de entrega para que você possa revisar falhas, tentar novamente entregas, pausar destinos e alternar segredos nas configurações da API do espaço de trabalho.
Verifique assinaturas de webhook
Verifique a assinatura antes de confiar na carga.
O SDK TypeScript faz isso para você e lança em vez de retornar um booleano para que um manipulador não esqueça de verificar:
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);
});
Para verificar você mesmo, compare o HMAC com {timestamp}.{body} em tempo constante. Observe a verificação do comprimento: crypto.timingSafeEqual é lançado quando os dois buffers diferem em comprimento, que um invasor controla.
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);
});
Sempre verifique o corpo da solicitação bruta. Se sua estrutura analisar JSON antes da verificação, a verificação de assinatura poderá falhar ou tornar-se não confiável.
Kanera também envia X-Kanera-Timestamp e X-Kanera-Event-Id. Rejeite entregas cujo carimbo de data/hora esteja fora de alguns minutos para a reprodução vinculada e use o ID do evento para tornar seu manipulador idempotente, pois as entregas podem ser repetidas.
Opções de saída relacionadas
Webhooks são o caminho de uso geral. Existem duas opções mais restritas para públicos específicos:
| Caminho | Público | Carga útil | Onde configurar | Plano |
|---|---|---|---|---|
| Webhooks | Outro sistema | JSON assinado em todo o catálogo de eventos | Configurações do espaço de trabalho -> API | Pró ou teste |
| Destinos de bate-papo | Um canal de equipe | Mensagens formatadas para Slack, Discord, Telegram ou Zulip | Configurações do espaço de trabalho -> Integrações | Pró ou teste |
| Canais de entrega pessoal | Uma pessoa | ntfy, Gotify ou JSON assinado para suas próprias notificações | Configurações de perfil -> Notificações | Pró ou teste |
| Assinaturas de eventos MCP | Host de um agente de IA | Cartão assinado e ocorrências de comentários para um retorno de chamada verificado pelo agente | O agente assina pelo MCP; nada para configurar em Kanera | Cada plano |
Os destinos de chat são gerenciados separadamente dos endpoints de webhook e não aparecem na lista de webhooks, portanto, a rotação de um segredo de webhook nunca afeta um destino de chat.
Uma automação Chame um webhook a ação é direcionada e não baseada em assinatura. Ele envia automation:webhook:called somente para o ponto final selecionado na regra, independentemente do valor normal desse ponto final eventTypes filtro, mantendo o mesmo comportamento de assinatura, repetição e histórico de entrega. Veja Automações.