Webhooks

Un webhook saliente avisa a tu sistema cada vez que algo cambia en Orkestra. Para ir en la otra dirección —que tu sistema cree tareas o actualice estados— usa un token personal con la API REST.

Outbound webhooks

Cuando un evento ocurre en tu organización (tarea creada, estado cambiado, comentario añadido, etc.), Orkestra envía un POST a la URL que configures. Los eventos están firmados con HMAC para que puedas verificar que vienen de Orkestra.

Qué proyectos envía

Quien recibe un webhook lee todo lo que le llega, y no tiene cuenta en Orkestra que diga qué puede ver. Por eso, si no eliges nada, un webhook solo envía lo de los proyectos que ve toda la organización, y los objetivos que no son de ningún proyecto. Los proyectos privados y los de un área no salen.

Si quieres que salgan, elige en el webhook qué envía: un proyecto que eliges sale aunque sea privado, y un área envía sus proyectos y los de las áreas que tiene debajo, menos los privados. Un webhook con algo elegido envía solo eso.

Eventos soportados

Los eventos que puedes suscribir:

  • task.created — tarea nueva
  • task.updated — se cambió algo de la tarea (también cuando la mueves de columna o cambias a quién está asignada)
  • task.moved — la tarea cambió de columna; trae la columna de origen (fromState) y la de destino (toState). Mover una tarea dentro de la misma columna no lo envía
  • task.assigned — alguien quedó asignado a la tarea, ya sea la primera asignación o una persona que se suma a las que ya estaban (addedAssigneeIds). Guardar la misma lista de personas, o quitar a alguien, no lo envía
  • task.reassigned — la tarea pasó de una persona a otra (fromUserId, toUserId)
  • task.deadline_approaching — falta menos de un día para el vencimiento de la tarea
  • task.overdue — el vencimiento ya pasó y la tarea sigue sin terminar
  • task.deleted — tarea eliminada
  • comment.created, comment.updated, comment.deleted
  • subtask.created, subtask.updated, subtask.deleted
  • goal.created, goal.updated, goal.deleted

task.deadline_approaching y task.overdue salen una sola vez por vencimiento: si cambias la fecha, vuelven a salir para la nueva. Una tarea ya terminada no los envía. Los cuatro eventos de tarea de arriba que son nuevos respetan lo que elegiste en «Qué proyectos envía»; las personas aparecen solo por su identificador, nunca con su nombre ni su teléfono.

Para reaccionar a un cambio, escucha el webhook en vez de consultar la API cada tanto: la API limita cuántos pedidos puedes hacer.

Un ejemplo completo, con un bot de WhatsApp propio, está en Conecta tu bot de WhatsApp.

Formato del payload

Cada webhook recibe un JSON con esta estructura:

  • event — nombre del evento (ej: task.moved); también viaja en el header X-Orkestra-Event
  • timestamp — fecha y hora ISO 8601
  • organizationId — ID de la organización donde ocurrió
  • data — objeto con el recurso afectado; en las tareas, projectId y task con id y title

Verificación HMAC

Cada request incluye el header X-Orkestra-Signature con un HMAC-SHA256 del body usando tu webhook secret. Para verificar:

  1. Toma el body crudo del request (sin parsear).
  2. Calcula HMAC-SHA256(body, tu_secret).
  3. Compara con el header en tiempo constante (usa crypto.timingSafeEqual en Node).

Retry inteligente

Orkestra reintenta entregas fallidas con esta lógica:

  • 5xx / timeout: reintento con backoff exponencial (1s, 5s, 30s, 2min, 10min, 1h).
  • 4xx (excepto 429): fallo permanente, no se reintenta. Verás el error en el log.
  • 429: respeta Retry-After si lo envías, o aplica backoff exponencial.
  • Tras 6 intentos fallidos, el webhook se marca como fallido y se notifica al admin.

Crear cosas desde tu sistema

Para que un servicio externo cree tareas o actualice estados, usa un token personal con la API REST (en beta). Todo lo que haga queda firmado con tu nombre y el del token, y puedes revocarlo cuando quieras.

Entradas firmadas (en beta)

Otra forma, sin escribir código contra la API: en Ajustes de la organización → Conexiones → Webhooks crea una entrada. Elige si deja una tarea (en un proyecto) o una fila (en una tabla) y átala a una de tus llaves personales. Lo que llegue queda a tu nombre y con los permisos de esa llave; si la revocas o vence, la entrada deja de recibir.

Cada mensaje es un POST con un registro en JSON a la dirección de la entrada, firmado con su secreto:

  • X-Orkestra-Timestamp: la hora en segundos.
  • X-Orkestra-Signature: v1= seguido del HMAC-SHA256 en hexadecimal de marca-de-tiempo.cuerpo.

Un mensaje vale 5 minutos y no se acepta dos veces. Tareas: title (obligatorio), description, priority, deadline (ISO 8601), labels. Filas: { "values": { "Columna": "valor" } }, por nombre o id de columna. Un campo que no existe se rechaza con un error claro. Cada organización puede enviar hasta 120 mensajes por minuto.

Monitoring

Todos los webhooks tienen un log con los últimos 30 días de actividad: status, latency, payload, respuesta. Útil para debugging cuando algo no funciona.

Los webhooks consumen rate limits dedicados (100 req/minuto). Si tu servicio genera muchos eventos, usa batching en lugar de un evento por cambio.