Configuracion de webhooks

Los webhooks permiten que Almirant envie notificaciones HTTP automaticas a tu servidor cuando ocurren eventos en tus proyectos. Cada vez que se crea un work item, se mueve una tarea entre columnas o se cierra un sprint, Almirant hace un POST a la URL que configures con los datos del evento.

Esto es util para:

• Sincronizar Almirant con herramientas externas (Slack, Discord, tu propio dashboard)
• Disparar pipelines de CI/CD cuando una tarea cambia de estado
• Alimentar sistemas de analytics o reporting
• Automatizar flujos personalizados fuera de Almirant

Crear un webhook

1. Ve a Configuracion > Webhooks en tu proyecto
2. Haz clic en Crear webhook
3. Completa los campos:

Campo	Descripcion	Ejemplo
URL	Endpoint HTTPS que recibira las notificaciones	https://mi-servidor.com/webhooks/almirant
Eventos	Tipos de eventos que disparan el webhook	work_item.created, sprint.closed
Secret	Clave secreta para validar la autenticidad de las peticiones	Se genera automaticamente o puedes definir uno propio

4. Haz clic en Guardar

Importante

La URL debe ser accesible desde internet y usar HTTPS. Almirant no enviara webhooks a URLs HTTP sin cifrar (excepto localhost en desarrollo).

Eventos disponibles

Selecciona uno o varios eventos al crear el webhook:

Evento	Se dispara cuando...
work_item.created	Se crea un nuevo work item
work_item.updated	Se modifican campos de un work item (titulo, descripcion, prioridad, etc.)
work_item.moved	Se mueve un work item entre columnas del board
work_item.archived	Se archiva un work item
lead.created	Se crea un nuevo lead en el CRM
lead.updated	Se actualizan datos de un lead
lead.stage_changed	Un lead cambia de etapa en el funnel
sprint.created	Se crea un nuevo sprint
sprint.closed	Se cierra un sprint

Consejo

Si solo necesitas reaccionar a cambios en el tablero, selecciona unicamente los eventos work_item.*. Cuantos menos eventos suscribas, menos trafico recibira tu servidor.

Verificar la firma del webhook

Cada peticion incluye una firma HMAC-SHA256 en el header X-Almirant-Signature que permite verificar que la peticion realmente proviene de Almirant y no fue manipulada.

Como funciona la verificacion

1. Almirant genera un hash HMAC-SHA256 del body de la peticion usando tu secret como clave
2. Incluye el hash en el header X-Almirant-Signature
3. Tu servidor recalcula el hash con el mismo secret y compara

Ejemplo en Node.js

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// En tu endpoint:
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // Body como string, no parseado

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Firma invalida' });
  }

  const event = JSON.parse(rawBody);
  console.log('Evento recibido:', event.type);

  // Procesar el evento...

  res.status(200).json({ received: true });
});

Ejemplo en Python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Seguridad

Siempre verifica la firma antes de procesar el evento. Nunca confies en los datos del webhook sin validar su autenticidad. Usa timingSafeEqual (o equivalente) para evitar ataques de timing.

Ver logs de entregas

Cada webhook mantiene un historial de entregas que puedes consultar para depurar problemas.

1. Ve a Configuracion > Webhooks
2. Haz clic en el webhook que quieres inspeccionar
3. En la pestana Entregas, veras una lista con:

Columna	Descripcion
Fecha	Momento exacto de la entrega
Evento	Tipo de evento que disparo la entrega
Estado	Codigo HTTP de respuesta (200, 500, timeout, etc.)
Duracion	Tiempo de respuesta de tu servidor

Haz clic en cualquier entrega para ver el detalle completo: headers enviados, body del payload y respuesta de tu servidor.

Reintentos y fallos

Almirant reintenta las entregas fallidas automaticamente con backoff exponencial:

Intento	Espera antes del reintento
1	Inmediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas

Se considera un fallo cuando:

• Tu servidor responde con un codigo HTTP >= 400
• Tu servidor no responde en 10 segundos (timeout)
• No se puede establecer conexion con tu servidor

Despues de 5 intentos fallidos, la entrega se marca como fallida y no se reintenta mas. Puedes reenviar manualmente desde el log de entregas.

Nota

Tu servidor debe responder con un codigo HTTP 2xx (idealmente 200) lo mas rapido posible. Si necesitas hacer procesamiento largo, acepta el webhook inmediatamente y procesa los datos de forma asincrona.

Desactivar o eliminar un webhook

• Desactivar: En la lista de webhooks, usa el toggle para desactivar temporalmente. Las entregas se pausan pero la configuracion se mantiene.
• Eliminar: Haz clic en el icono de eliminar. Esta accion es irreversible y borra tambien el historial de entregas.