Webhooks para la gestión de proyectos explicados por Celoxis: alertas de proyectos en tiempo real, configuración y seguridad

Un webhook de Celoxis es una instrucción permanente: cuando ocurre una actividad específica en Celoxis, como la creación de un proyecto, el cambio de estado de una tarea o la aprobación de un gasto, Celoxis envía automáticamente esa actualización a una URL que usted especifique. Usted elige qué actividades son relevantes, proporciona un punto final HTTPS y Celoxis se encarga del resto. Nadie tiene que recordar reenviar el mensaje, ya que el sistema lo hace en el momento en que ocurre el cambio.

Esto es importante porque la alternativa, comprobar Celoxis repetidamente a través de la API para ver si algo ha cambiado, es lenta, consume muchas llamadas a la API y, además, deja un lapso de tiempo entre el cambio y el momento en que tu equipo se entera. Un webhook elimina ese lapso.

Cada envío es una solicitud JSON POST firmada. Su punto final recibe el evento, confirma que proviene de Celoxis y luego realiza la acción correspondiente: notificar a un canal, crear un registro en el CRM, iniciar un flujo de trabajo de facturación o enviar el cambio a un almacén de datos.

Toda oficina de gestión de proyectos (PMO) acaba encontrándose con el mismo obstáculo: el sistema de gestión de proyectos contiene la información veraz, pero esta debe llegar a otros cinco lugares. Un CRM. Un canal de Slack. Una herramienta de contabilidad. Un panel de BI. Ninguno de esos lugares consulta Celoxis por sí solo. Alguien tiene que salvar esa brecha, y durante mucho tiempo ese alguien era una persona que lo hacía manualmente, o un script que consultaba la API cada sesenta segundos con la esperanza de detectar alguna novedad.

El sondeo tiene un coste específico y silencioso. Se invierte tiempo en llamadas a la API preguntando "¿hay novedades?" y obteniendo "no" en la gran mayoría de los casos, hasta el momento crucial, cuando la integración aún lleva un minuto de retraso. En un solo proyecto, esto es tolerable. Sin embargo, en una cartera completa, se traduce en infraestructura desperdiciada y un sistema que siempre parece ir un paso por detrás.

Existe un segundo problema, más específico, que se ha manifestado en el sector del software de gestión de proyectos. Varias plataformas consolidadas diseñaron sus sistemas de webhook con un enfoque de todo o nada: al suscribirse, se reciben todos los eventos, todas las ediciones de celdas, todos los comentarios y todos los cambios menores, mezclados con la única señal deseada. Los equipos terminaron creando su propia capa de filtrado solo para descartar la mayor parte de la información recibida. Algunos proveedores están incorporando ahora el filtrado de eventos en sistemas que originalmente no lo incluían, lo que evidencia la frecuencia de esta deficiencia.

Los eventos de webhook de Celoxis se definen desde el principio por tipo de elemento y acción. Puedes suscribirte a la adición de un proyecto, la actualización de una tarea o la eliminación de un gasto de forma independiente. Esto evita por completo la necesidad de una adaptación posterior. Más información sobre su funcionamiento a continuación.

El mecanismo es sencillo por diseño. Siempre se dan tres pasos:

1. En Celoxis se produce una actividad. Alguien crea un proyecto, actualiza una tarea, registra el tiempo o aprueba un gasto.
2. Celoxis comprueba tu suscripción. Si tu webhook está configurado para detectar esa actividad específica, se pasa al paso tres. Si no, no ocurre nada.
3. Celoxis envía una notificación firmada mediante POST a la URL de tu punto final. Tu sistema recibe la actualización prácticamente en tiempo real.

Si el punto final no está disponible o devuelve un error, Celoxis no descarta el evento. Lo reintenta automáticamente con un mecanismo de retroceso, y también puede reintentar la entrega manualmente desde la interfaz de administración una vez que el destino vuelva a estar operativo. Una entrega se considera exitosa cuando el punto final devuelve una respuesta HTTP 2xx.

Eventos a los que puedes suscribirte

Cada webhook detecta las acciones de Agregar, Actualizary Eliminar en los tipos de elementos que elijas. No estás obligado a aceptar todo lo que Celoxis puede enviar. Tú seleccionas lo que te interesa.

Aquí tenéis algunos ejemplos reales de cómo se ve esto en la práctica:

• Se crea un proyecto y aparece automáticamente una oportunidad en el CRM.
• Se agrega una tarea y se notifica al canal de Slack correcto sin que nadie escriba un mensaje.
• Se aprueba un gasto y se notifica al departamento de contabilidad en el mismo minuto, no en la siguiente sincronización por lotes.
• Se registra el tiempo y se inicia automáticamente un proceso de facturación.

Empiece con uno o dos eventos, no con los seis. Cuantos más eventos, más notificaciones llegarán a su dispositivo, y la mayoría de las integraciones solo necesitan una pequeña parte de la actividad para funcionar correctamente.

Aspecto de la carga útil

Cada entrega es un array JSON. Celoxis puede agrupar varios eventos coincidentes en una sola solicitud POST, por lo que el receptor debe iterar sobre el array en lugar de asumir que se trata de un único objeto.

Un evento típico de tarea modificada tiene este aspecto:

Ejemplo de carga útil de webhook

JSON

[ { "type": "tasks.modified", "eventId": "<unique-event-id> ", "ocurrióEn": "<UTC ISO timestamp> ", "actor": { "value": 123, "text": "Alex Morgan" }, "resource": { "type": "tasks", "id": 456, "text": "Preparar la presentación inicial del cliente", "url": "https://app.celoxis.com/..." }, "changes": [ { "field": "name", "label": "Name", "previous": { "value": "Draft kickoff deck", "text": "Draft kickoff deck" }, "current": { "value": "Preparar la presentación inicial del cliente", "text": "Preparar la presentación inicial del cliente" } } ] } ]

Algunos detalles que ahorran tiempo durante la implementación:

• Los cambios aparecen en los eventos de actualización (*.modified). Los eventos de adición y eliminación no incluyen una diferencia campo por campo.
• Las cargas útiles eliminadas conservan el tipo y el ID del recurso. El nombre y la URL se omiten porque el registro ya no existe.
• La aprobación o el rechazo de un gasto llega como `gastos.modificados`, no como un tipo de evento separado.
• Utilice eventId y X-Celoxis-Delivery-Id para el registro y la idempotencia, de modo que un reintento no cree un mensaje duplicado en Slack ni una segunda línea de factura.

Tu servidor debería responder rápidamente con un código 200, 201 o 204. Realiza el procesamiento principal después de confirmar la solicitud. Si Celoxis no puede obtener un código 2xx, la entrega queda pendiente y se reintenta.

Antes de comenzar, necesitas dos cosas: acceso de administrador con el de Acceso a Webhooks y una URL de punto final donde Celoxis deba enviar notificaciones. Utiliza HTTPS en producción.

1. Abre la página de Webhooks. Desde el menú de tu perfil, ve a Administración, luego a Integraciones y, por último, a Webhooks. Si aún no hay ninguno, la lista estará vacía.
2. Haz clic en + Agregar. Esto abrirá el formulario Agregar Webhook.
3. Rellena el formulario.
   • Nombre: algo claro, como "Notificar a Slack, nuevas tareas", para que cualquiera que revise tus webhooks más adelante sepa para qué sirve.
   • URL: su punto final, introducido con cuidado
   • Secreto: haga clic en Generar secreto. Celoxis utiliza esto para firmar cada notificación que envía. Su sistema receptor utiliza el mismo secreto para confirmar que la solicitud es genuina. Los secretos generados comienzan con whsec_
   • Activado: deja esta opción activada para empezar a recibir notificaciones inmediatamente.
   • Eventos: elige al menos una actividad de la lista anterior.
4. Guardar. Tu webhook ahora aparece en la sección "Tus URL de webhook".

Desde allí, puedes editar el nombre, la URL, la clave secreta o la selección de eventos en cualquier momento, deshabilitar un webhook temporalmente sin eliminarlo o eliminarlo permanentemente si estás seguro de que no lo volverás a necesitar.

Un límite que conviene tener en cuenta: Celoxis permite hasta cinco webhooks por empresa. Analice detenidamente sus necesidades de integración antes de crearlos uno a uno. Si necesita que varios sistemas posteriores reaccionen a los mismos eventos, dirija un webhook a un enrutador interno o a una plataforma iPaaS y, a partir de ahí, expanda la red, en lugar de ocupar un espacio por destino.

Si actualiza la URL del punto final, las entregas pendientes y fallidas se redirigen a la nueva dirección. Los eventos ya entregados permanecen sin cambios.

Esta es la sección que probablemente más le importe a un CTO que esté revisando si es seguro exponer los webhooks a un punto final externo, y vale la pena comprenderla correctamente en lugar de leerla por encima.

Cada solicitud que envía Celoxis incluye tres encabezados junto con el cuerpo JSON:

Cómo se genera la firma

Celoxis une la marca de tiempo y el cuerpo del mensaje sin procesar con un punto, luego procesa ese texto combinado a través de HMAC-SHA256 usando su clave secreta:

HMAC-SHA256(secreto, “{marca de tiempo}.{cuerpo sin procesar}”)

El resultado se envía como el valor v1= en X-Celoxis-Signature. El mismo secreto y el mismo mensaje siempre producen la misma firma, pero no hay forma de revertir la firma para obtener el secreto original.

Cómo verificarlo por tu parte

1. Utilice el mensaje tal como lo recibe. No lo reformatee ni lo reconstruya previamente, ya que incluso un pequeño cambio podría provocar que la coincidencia falle.
2. Extrae la marca de tiempo y la firma de los encabezados de la solicitud.
3. Recrea la firma tú mismo utilizando HMAC-SHA256 y tu copia del secreto.
4. Compara ambos. Si coinciden, la solicitud es legítima y puedes aceptarla. Si no coinciden, recházala.

Como paso adicional recomendado, rechace cualquier solicitud cuya marca de tiempo sea anterior a unos minutos (cinco minutos es un valor predeterminado razonable), para evitar que un mensaje interceptado pueda reproducirse posteriormente. Celoxis no lo exige, pero es una buena práctica.

Aquí tenéis un boceto en Node.js de la misma comprobación:

Verificar una firma de webhook de Celoxis

Node.js

const crypto = require("crypto"); function verifyCeloxisWebhook({ rawBody, timestamp, signatureHeader, secret }) { const expected = crypto .createHmac("sha256", secret) .update(`${timestamp}.${rawBody}`) .digest("hex"); const actual = new URLSearchParams( signatureHeader.replace(/,/g, "&") ).get("v1"); const ageSeconds = Math.abs( Date.now() / 1000 - Number(timestamp) ); if (!actual || ageSeconds > 300) return false; return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(actual) ); }

Mantén el secreto en privado. Cualquiera que lo tenga podría crear solicitudes falsas que parezcan legítimas. Si regeneras el secreto, actualízalo también en el receptor, o el anterior dejará de funcionar y todas las solicitudes fallarán la verificación. Ambos lados deben coincidir exactamente.

El acceso a los webhooks está restringido a los administradores, e incluso en ese caso, un rol necesita el permiso específico de Acceso a Webhooks para poder abrir la página de Webhooks. Sin este permiso, los usuarios verán un mensaje de Permiso Denegado.

Esta función también está restringida por plan. Si Webhooks no está habilitado en tu plan, el menú no aparecerá. Ponte en contacto con tu administrador de Celoxis o con el soporte técnico de Celoxis si esperabas verlo y no aparece.

Un administrador otorga el permiso desde el menú principal, luego en Administración, luego en Configuración, luego en Control de acceso, en la pestaña Empresa, configurando el Acceso a webhooks en Conceder para el rol correspondiente.

Esto es más importante de lo que parece a primera vista. Los webhooks transmiten información confidencial y mantienen una conexión directa con sistemas externos, y una configuración incorrecta o una integración deficiente pueden provocar fugas de información o interferencias rápidamente. Las recomendaciones de Celoxis son claras al respecto: no se debe otorgar acceso a los webhooks a los usuarios del cliente. Esta es una medida de precaución sensata para cualquier organización que gestione datos confidenciales de proyectos o financieros entre partes interesadas internas y externas.

Configurar un webhook no es el final del trabajo. Saber si realmente funciona es igual de importante, y Celoxis divide esto en dos vistas.

sección «Entregas recientes», que se encuentra en la página de detalles del webhook, muestra los intentos de entrega pendientes y fallidos más recientes. Está diseñada para ayudarte a detectar problemas rápidamente, no para ser un registro completo. Si está vacía, no significa que no se haya enviado nada. Significa que no hay entregas pendientes ni fallidas en este momento. Las entregas exitosas se encuentran en otra sección.

La opción "Ver todo" abre el historial completo de entregas en un panel deslizante, que incluye todo lo marcado como "Entregado", "Pendiente" o "Fallido". Al hacer clic en el icono del ojo en cualquier fila, se muestra el detalle completo de la entrega en formato JSON, incluyendo el estado, el número de intentos, el código de respuesta HTTP y la carga útil exacta que envió Celoxis.

El estado de la entrega se divide en tres estados:

Para cualquier problema pendiente o fallido, primero solucione la causa subyacente (una URL incorrecta o un sistema receptor caído) y luego utilice la opción Reintentar. Las entregas exitosas no se pueden reintentar, que es el comportamiento deseado: ya se han realizado.

Esta vista integrada en el producto marca la diferencia entre descubrir uno mismo un problema de integración y enterarse de ello por parte de un cliente dos semanas después.

La mayoría de los problemas con los webhooks se deben a unas pocas causas. Aquí te explicamos qué suele fallar y cómo solucionarlo.

Los casos de uso que aparecen con mayor frecuencia siguen un patrón: algo cambia en Celoxis y un sistema diferente necesita reaccionar sin la intervención de una persona.

• Sincronización con el CRM: un nuevo proyecto activa automáticamente un acuerdo o registro correspondiente, de modo que las ventas y la entrega se mantienen alineadas sin necesidad de introducir datos manualmente.
• Notificaciones de equipo: la creación de tareas o los cambios de estado llegan a Slack o Teams en el momento en que ocurren, en lugar de aparecer en una reunión de estado dos días después.
• Automatización de la facturación: el tiempo registrado o un gasto aprobado se integra directamente en los flujos de trabajo de facturación o nómina.
• Inteligencia empresarial e informes: los datos de proyectos y tareas se envían continuamente a un almacén de datos o panel de control, en lugar de depender de una exportación por lotes nocturna que siempre está un poco desactualizada.
• Flujos de trabajo entre herramientas: conectar Celoxis con Jira, Salesforce, ServiceNow o un sistema interno diseñado específicamente para la forma en que funciona su organización.

Ninguna de estas opciones requiere scripts de sondeo personalizados ni tareas programadas para comprobar si hay cambios. Solo requieren un webhook, configurado para los eventos correctos y apuntando al punto final adecuado.

Si estás comparando plataformas, y no simplemente adoptando la herramienta de gestión de proyectos que te ofrezca la plataforma, hay algunas preguntas clave que distinguen un sistema de webhooks que funciona bien en producción de uno que se convierte en una carga de mantenimiento a los seis meses.

1. ¿Puedes suscribirte a eventos específicos o solo a todos a la vez? Las secuencias de eventos amplias y sin filtrar implican que tendrás que crear tu propia lógica de filtrado posteriormente, lo que supone código adicional que mantener y una mayor probabilidad de errores.
2. ¿Cada solicitud está firmada y la verificación está documentada? Un webhook sin verificación de firma es vulnerable. Pregunte específicamente cómo funciona la firma, no solo si existe. Necesita HMAC, una marca de tiempo y un ID de entrega, no un encabezado compartido que cualquiera pueda copiar.
3. ¿Puedes ver el historial de entregas o estás trabajando a ciegas? Si un webhook falla silenciosamente durante dos semanas, necesitas una forma de averiguarlo que no sea simplemente "un cliente menciona que su integración parece estar rota".
4. ¿Está realmente restringido el acceso para crear y administrar webhooks? Cualquiera con la capacidad de crear un webhook puede redirigir datos confidenciales del proyecto a un servidor externo. Esto debería estar sujeto a un permiso específico, no ser un acceso de administrador general por defecto.
5. ¿Cuál es el límite práctico? Un límite estricto de webhooks por cuenta está bien, pero necesitas saber que existe antes de diseñar cinco integraciones diferentes partiendo de la base de que puedes crear una sexta.

Celoxis responde a esas cinco preguntas en la interfaz de administración: filtros a nivel de evento, firma HMAC-SHA256 con marca de tiempo e ID de entrega, un historial de entrega integrado con un visor de carga útil JSON, un permiso dedicado de Acceso a Webhooks y un límite publicado de cinco webhooks por empresa.

Todas las plataformas de esta categoría incluyen webhooks de alguna forma. Las diferencias radican en la granularidad, la configuración de seguridad predeterminada y el nivel de visibilidad que se obtiene una vez que la aplicación está en funcionamiento. Esta comparación se basa en la documentación pública para desarrolladores de cada proveedor, disponible al momento de redactar este texto.

Aquí destacan algunos aspectos. Celoxis y Wrike admiten el filtrado de eventos a nivel de cuenta o de empresa sin necesidad de un webhook independiente por tablero, algo que monday.com sí requiere. Celoxis es también una de las pocas plataformas de este grupo donde la verificación de firmas, el monitoreo de entregas y el control de permisos están integrados en la experiencia de administración básica, en lugar de requerir una llamada a la API o una herramienta de terceros para su verificación. Asana y monday.com se centran más en herramientas para desarrolladores que en una interfaz integrada, lo cual funciona bien para un equipo de ingeniería especializado, pero genera inconvenientes si la oficina de gestión de proyectos (PMO) necesita visibilidad sin involucrar al departamento de TI en cada verificación.

Ninguna plataforma es objetivamente la mejor en todos los aspectos. Si tu equipo prioriza las API y ya cuenta con un sólido soporte de ingeniería, el modelo de Asana es viable. Si necesitas una visibilidad amplia e integrada sin necesidad de crear una capa de monitorización aparte, la vista de entregas integrada de Celoxis es la opción más directa.

Los webhooks solucionan un problema específico y recurrente: mantener los sistemas sincronizados sin la intervención de una persona ni de un script de sondeo lento. Los webhooks de Celoxis ofrecen control a nivel de evento desde el principio, un proceso de verificación HMAC-SHA256 documentado y una vista de monitorización de entregas integrada en el panel de administración, en lugar de una funcionalidad añadida por separado.

Que sea la opción adecuada depende de a qué conectes Celoxis, de cuánto soporte técnico tengas disponible para construir y mantener el lado receptor, y de cuántas integraciones necesites ejecutar simultáneamente.

Si estás comparando esto con tu configuración actual, los pasos de configuración anteriores tardan unos minutos en probarse de principio a fin, lo cual suele ser suficiente para saber si se ajusta a tus necesidades.

Configurar tu primer webhook lleva unos diez minutos si tu endpoint está listo, y es una buena forma de ver las cargas útiles reales antes de comprometerte con una integración más compleja. Si prefieres ver todo el proceso con los datos de tu propio proyecto, reserva una demo de Celoxis o inicia una prueba gratuita y pruébalo allí.