Ganchos web
Los webhooks permiten que los sistemas externos reaccionen cuando el trabajo cambia en Kanera.
Utilice webhooks cuando otro sistema deba conocer los cambios sin sondear la API constantemente. Los ejemplos comunes incluyen:
- Actualizar un panel externo.
- Sincronizar tarjetas cambiadas con otro sistema.
- Activar implementación o revisar flujos de trabajo.
- Registre la actividad de Kanera en un sistema de auditoría.
Para publicar la actividad de la tarjeta en un canal de chat del equipo, no necesita un webhook propio. Kanera tiene incorporado Destinos de chat para Slack, Discord, Telegram y Zulip que dan formato a cada mensaje para la plataforma. Utilice un webhook cuando necesite el catálogo de eventos completo, cargas útiles exactas y verificación de firma.
Los administradores del espacio de trabajo pueden crear puntos finales de webhook desde Configuración del espacio de trabajo -> API, en el Webhooks personalizados sección. los tableros independientes tienen el mismo API pestaña en su propia configuración del tablero. Las integraciones también pueden registrar puntos finales a través de la API pública o el SDK de TypeScript.
Cada destino de webhook puede recibir todos los eventos o solo tipos de eventos seleccionados. salir eventTypes vacío para recibir cada evento, o proporcione una o más de las cadenas de tipo de evento a continuación.
Plano y permisos
- Los administradores del espacio de trabajo pueden ver y administrar todos los puntos finales de webhook genéricos en ese espacio de trabajo.
- Una credencial API con capacidad de escritura o un agente OAuth interactivo puede registrar un punto final sin autoridad de administrador cuando su usuario es miembro del espacio de trabajo. Ese punto final tiene como ámbito la conexión que se está creando: solo los mismos administradores de conexión y espacio de trabajo pueden verlo o administrarlo. Las credenciales con alcance de lectura no pueden administrar webhooks.
- Se necesitan webhooks Pro o los 30 días prueba profesional. No están disponibles en alojamiento gratuito.
- En el alojamiento gratuito, el formulario de creación se reemplaza por Los webhooks no están disponibles en tu plan.
Al revocar la credencial o la conexión del agente también se eliminan los puntos finales del ámbito de la conexión. Los puntos finales del espacio de trabajo creados por el administrador permanecen hasta que un administrador los elimina.
¿Qué sucede en una rebaja?
Cuando una organización alojada pasa de Pro o una versión de prueba a Free, Kanera pausa cada punto final de webhook habilitado en lugar de eliminar nada. También revoca las claves API del espacio de trabajo (las claves personales siguen funcionando) y deshabilita las automatizaciones más allá del límite gratuito.
| En alojado Gratis | Comportamiento |
|---|---|
| Puntos finales existentes | Se pausan automáticamente y no se pueden volver a habilitar mientras la organización esté en modo gratuito. |
| Nueva actividad | No llega a su punto final. |
| Algo todavía esperando para enviar | Registrado como fallido con webhooks are unavailable on the current plan en lugar de enviar tarde. |
| Una entrega fallida | No se puede volver a intentar manualmente. |
| Configuración e historia | Mantenido. Los puntos finales, las selecciones de eventos, los secretos y el historial de entrega siguen ahí. |
Volver a actualizar a Pro vuelve a habilitar los puntos finales que fueron pausados por la degradación y restaura las claves API del espacio de trabajo que revocó, por lo que no es necesario reconstruir una integración reanudada.
Registrar un punto final mediante programación
La API pública expone el mismo ciclo de vida de punto final genérico utilizado por la configuración del espacio de trabajo. Cada ruta a continuación es relativa a:
/api/v1/workspaces/{workspaceId}/webhooks
| Método | Camino | uso |
|---|---|---|
GET | (ruta base) | Enumera los puntos finales visibles para la persona que llama. |
POST | (ruta base) | Cree un punto final y devuelva su secreto de firma una vez. |
PATCH | /{endpointId} | Cambie su nombre, URL, filtro de eventos o estado habilitado. |
POST | /{endpointId}/secret | Gire el secreto de firma. |
DELETE | /{endpointId} | Eliminar el punto final. |
GET | /{endpointId}/deliveries | Lea los intentos de entrega recientes. |
POST | /{endpointId}/deliveries/{deliveryId}/retry | Vuelva a intentar una entrega fallida. |
Con el SDK de TypeScript, utilice kanera.webhookEndpoints.create(), .list(), .update(), .rotateSecret(), .deliveries(), .retryDelivery(), y .delete(). El punto final devuelto tiene scope: "workspace" para un punto final administrado por administrador o scope: "connection" cuando una credencial no administrativa lo registró. Guarde el secret devuelto por creación o rotación inmediatamente; las lecturas posteriores nunca lo exponen.
Tipos de eventos de webhook
La API pública expone la lista actual en:
https://api.kanera.app/webhook-event-types
| Área | Tipos de eventos |
|---|---|
| Listas | list:created, list:updated, list:moved, list:rebalanced, list:deleted |
| Separadores de tableros | separator:created, separator:updated, separator:moved, separator:rebalanced, separator:deleted |
| Campos personalizados | customField:created, customField:updated, customField:moved, customField:rebalanced, customField:deleted |
| Opciones de campos personalizados | customFieldOption:created, customFieldOption:updated, customFieldOption:moved, customFieldOption:rebalanced, customFieldOption:deleted |
| Tarjetas | card:created, card:updated, card:moved, card:rebalanced, card:deleted |
| Campos personalizados de tarjeta | card:customFieldValue:set, card:customFieldValue:cleared |
| Etiquetas de tarjetas y asignatarios | card:labels:set, card:assignees:set |
| Adjuntos de tarjetas | card:attachment:created, card:attachment:deleted |
| Listas de verificación de tarjetas | card:checklist:created, card:checklist:updated, card:checklist:moved, card:checklist:rebalanced, card:checklist:deleted |
| Elementos de la lista de verificación de la tarjeta | card:checklistItem:created, card:checklistItem:updated, card:checklistItem:moved, card:checklistItem:rebalanced, card:checklistItem:deleted |
| Etiquetas de tarjetas de espacio de trabajo | cardLabel:created, cardLabel:updated, cardLabel:moved, cardLabel:rebalanced, cardLabel:deleted |
| Comentarios | comment:created, comment:updated, comment:deleted |
| Reacciones de comentarios | comment:reaction:added, comment:reaction:removed |
| Alimentación de tarjetas | card:feedItem:created, card:feedItem:updated, card:feedItem:deleted |
| Tableros | board:created, board:updated, board:moved, board:rebalanced, board:deleted |
| Miembros de el tablero | board:member:added, board:member:removed |
| Espacios de trabajo | workspace:updated, workspace:deleted |
| Miembros del espacio de trabajo | workspace:member:added, workspace:member:updated, workspace:member:removed |
| Usuarios | user:profile:updated |
| Notas | note:created, note:updated, note:moved, note:rebalanced, note:deleted, note:locked, note:unlocked |
| El agente se ejecuta | agentRun:started, agentRun:updated |
Formato de carga útil
Kanera envía cada webhook como un objeto JSON con un sobre estable y específico para el evento. data.
| campo | Significado |
|---|---|
id | ID de evento de webhook único. Esto coincide X-Kanera-Event-Id. |
type | Tipo de evento, como card:created. |
workspaceId | Espacio de trabajo donde ocurrió el evento. |
boardId | Tablero donde ocurrió el evento, cuando el evento tiene el alcance del tablero. |
cardId | Tarjeta involucrada en el evento, cuando la carga útil del evento identifica una tarjeta. |
occurredAt | Marca de tiempo ISO 8601 de cuando ocurrió el evento. |
data | Carga útil completa del evento. La forma depende de type y coincide con la carga útil del evento en tiempo real correspondiente. |
Los eventos dirigidos por agentes se transmiten { boardId, cardId, run } en data, donde run es la ejecución completa del agente: su agentName, el userId actúa para, status, title, summary, externalUrl, y su startedAt, heartbeatAt, y endedAt marcas de tiempo. agentRun:updated se dispara en cada latido del corazón, así como en un cambio de estado, así que active a su controlador run.status en lugar de tratar cada entrega como un trabajo nuevo. Una carrera que deja de latir llega como una final agentRun:updated con status: "stalled".
Ejemplo 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 envía entregas de webhooks como JSON e incluye encabezados que puede utilizar para verificar la solicitud:
| encabezado | Significado |
|---|---|
X-Kanera-Event-Id | Identificación de evento única. |
X-Kanera-Timestamp | Marca de tiempo de Unix en segundos. |
X-Kanera-Signature | sha256= además de una firma HMAC-SHA256. |
La firma se calcula sobre:
${timestamp}.${rawBody}
utilizando el secreto del punto final del webhook.
Las entregas de webhook se reintentan cuando el punto final devuelve un estado que no es 2xx o no se puede alcanzar. Kanera registra el historial de entregas para que pueda revisar fallas, reintentar entregas, pausar destinos y rotar secretos desde la configuración de la API del espacio de trabajo.
Verificar firmas de webhooks
Verifique la firma antes de confiar en la carga útil.
el SDK de mecanografiado hace esto por usted y lanza en lugar de devolver un valor booleano para que el controlador no pueda olvidarse 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 verificarlo usted mismo, compare el HMAC {timestamp}.{body} en tiempo constante. Tenga en cuenta la verificación de longitud: crypto.timingSafeEqual lanza cuando los dos buffers difieren en longitud, que controla un atacante.
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);
});
Verifique siempre con el cuerpo de la solicitud sin formato. Si su marco analiza JSON antes de la verificación, la verificación de firma puede fallar o dejar de ser confiable.
Kanera también envía X-Kanera-Timestamp y X-Kanera-Event-Id. Rechace las entregas cuya marca de tiempo esté fuera de unos pocos minutos para su reproducción limitada y use la identificación del evento para hacer que su controlador sea idempotente, ya que las entregas pueden volver a intentarse.
Opciones de salida relacionadas
Los webhooks son la ruta de uso general. Existen dos opciones más limitadas para audiencias específicas:
| Camino | Audiencia | Carga útil | donde configurar | Plan |
|---|---|---|---|---|
| Ganchos web | Otro sistema | JSON firmado en todo el catálogo de eventos | Configuración del espacio de trabajo -> API | Pro o prueba |
| Destinos de chat | Un canal de equipo | Mensajes formateados para Slack, Discord, Telegram o Zulip | Configuración del espacio de trabajo -> Integraciones | Pro o prueba |
| Canales de entrega personales | una persona | ntfy, Gotify o JSON firmado para sus propias notificaciones | Configuración de perfil -> Notificaciones | Pro o prueba |
| Suscripciones a eventos de MCP | El anfitrión de un agente de IA | Tarjeta firmada y ocurrencias de comentarios en una devolución de llamada que el agente verificó | El agente se suscribe a través de MCP; nada que configurar en Kanera | Cada plan |
Los destinos de chat se administran por separado de los puntos finales de webhook y no aparecen en la lista de webhook, por lo que la rotación de un secreto de webhook nunca afecta un destino de chat.
una automatizacion Llamar a un webhook la acción está dirigida a un objetivo en lugar de estar basada en suscripción. envía automation:webhook:called sólo al punto final seleccionado en la regla, independientemente del valor normal de ese punto final. eventTypes filtro, manteniendo el mismo comportamiento de firma, reintento e historial de entrega. Ver Automatizaciones.