Notificaciones por Webhook

Los webhooks te permiten recibir notificaciones HTTP POST en tiempo real cada vez que algo cambia en tu espacio de trabajo de Archyl. Crea un webhook, apunta a tu URL, selecciona los eventos que te interesen y Archyl notificara a tu endpoint cada vez que esos eventos se disparen.

Descripcion general

Cuando ocurre un evento (se crea un sistema, se despliega un release, se actualiza un ADR), Archyl envia una solicitud HTTP POST a cada webhook suscrito a ese evento. Tu endpoint recibe un payload en formato JSON que describe lo que sucedio, quien lo hizo y a que proyecto pertenece.

Casos de uso habituales:

• Notificaciones en Slack o Teams cuando se realizan cambios en la arquitectura
• Disparadores de CI/CD cuando se crea un nuevo release
• Registro de auditoria en un sistema externo
• Dashboards personalizados que reaccionan a eventos de arquitectura
• Pipelines de automatizacion que se ejecutan cuando finalizan los descubrimientos

Eventos soportados

Elementos de arquitectura

Gestion de proyectos

Documentacion

Colaboracion y analisis

Crear un webhook

1. Ve a Configuracion de la organizacion y selecciona la pestana Webhooks
2. Haz clic en Nuevo Webhook
3. Completa la configuracion:

4. Haz clic en Crear

El webhook comienza a recibir eventos de inmediato.

Formato del payload

Cada entrega de webhook envia un payload JSON con esta estructura:

{
  "event": "system.created",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "entityType": "system",
    "entityName": "Payment Service",
    "action": "created",
    "userName": "vincent",
    "projectId": "a1b2c3d4-...",
    "projectName": "My Project"
  }
}

El header Content-Type siempre es application/json.

Seguridad

Headers de solicitud

Cada entrega de webhook incluye estos headers:

Verificacion de firma HMAC-SHA256

Si configuras un token secreto al crear el webhook, Archyl firma cada payload usando HMAC-SHA256. La firma se envia en el header X-Archyl-Signature con el formato:

sha256=<resumen HMAC-SHA256 codificado en hexadecimal>

Para verificar una entrega:

1. Lee el cuerpo crudo de la solicitud (los bytes exactos, antes de cualquier parseo de JSON)
2. Lee el header X-Archyl-Signature y elimina el prefijo sha256= para obtener la firma hexadecimal
3. Calcula un hash HMAC-SHA256 del cuerpo crudo usando tu token secreto como clave
4. Codifica el resultado en hexadecimal y comparalo con la firma del paso 2 usando una comparacion en tiempo constante
5. Rechaza la solicitud si no coinciden

Ejemplo en Go:

func verifyArchylWebhook(r *http.Request, secret string) ([]byte, error) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        return nil, err
    }

    header := r.Header.Get("X-Archyl-Signature")
    if !strings.HasPrefix(header, "sha256=") {
        return nil, fmt.Errorf("missing or invalid signature header")
    }
    signature := strings.TrimPrefix(header, "sha256=")

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(signature)) {
        return nil, fmt.Errorf("signature mismatch")
    }
    return body, nil
}

Ejemplo en Node.js:

const crypto = require("crypto");

function verifyArchylWebhook(req, secret) {
  const header = req.headers["x-archyl-signature"] || "";
  if (!header.startsWith("sha256=")) {
    throw new Error("Missing or invalid signature header");
  }
  const signature = header.slice("sha256=".length);

  const body = req.rawBody; // use raw body, not parsed JSON
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    throw new Error("Signature mismatch");
  }
  return JSON.parse(body);
}

Ejemplo en Python:

import hmac
import hashlib

def verify_archyl_webhook(body: bytes, header: str, secret: str) -> dict:
    if not header.startswith("sha256="):
        raise ValueError("Missing or invalid signature header")
    signature = header.removeprefix("sha256=")

    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Signature mismatch")
    return json.loads(body)

Usa siempre comparacion en tiempo constante (hmac.Equal, crypto.timingSafeEqual, hmac.compare_digest) para prevenir ataques de temporizado. Verifica siempre contra el cuerpo crudo de la solicitud: parsear y re-serializar el JSON puede cambiar la representacion en bytes y romper la firma.

Historial de entregas

Cada webhook guarda un registro de las entregas recientes. Para consultarlo:

1. Ve a Configuracion de la organizacion > Webhooks
2. Haz clic en el nombre del webhook
3. Abre la pestana Entregas

Cada entrada de entrega muestra:

Las entregas se conservan durante 7 dias. Despues de ese periodo, se eliminan automaticamente.

Una insignia verde indica una entrega exitosa (respuesta 2xx). Una roja indica un fallo (respuesta no 2xx o timeout).

Pruebas

Antes de depender de un webhook en produccion, verifica que funcione correctamente:

1. Abre la pagina de detalle del webhook
2. Haz clic en Enviar prueba
3. Archyl envia un payload de prueba a tu endpoint con event: "webhook.test"
4. Consulta la pestana de Entregas para confirmar la recepcion e inspeccionar la respuesta

La entrega de prueba utiliza el mismo mecanismo de firma que los eventos reales, por lo que puedes validar tu logica de verificacion de firmas al mismo tiempo.

Politica de reintentos

Cuando una entrega falla (respuesta no 2xx o timeout de red), Archyl reintenta automaticamente:

Despues de 3 reintentos fallidos, la entrega se marca como fallida. Puedes volver a activar manualmente cualquier entrega fallida desde la pestana de Entregas haciendo clic en Reintentar.

Si un webhook falla de forma continuada durante 24 horas, Archyl lo desactiva y envia una notificacion a los administradores de la organizacion. Reactivalo desde la configuracion del webhook una vez que el problema este resuelto.

Filtrado por proyectos

Por defecto, un webhook recibe eventos de todos los proyectos de la organizacion. Para limitar el alcance:

1. Edita el webhook
2. En Proyectos, selecciona uno o mas proyectos
3. Guarda los cambios

Solo los eventos originados en los proyectos seleccionados activaran entregas. Esto es util cuando diferentes equipos gestionan diferentes proyectos y solo necesitan notificaciones de su propio trabajo.

Puedes actualizar el filtro de proyectos en cualquier momento sin necesidad de recrear el webhook.

Buenas practicas

Responde rapido

Tu endpoint debe devolver una respuesta 2xx en menos de 10 segundos. Si necesitas realizar un procesamiento pesado, acepta el webhook de inmediato y gestiona el trabajo de forma asincrona en un job en segundo plano.

Verifica las firmas

Configura siempre un token secreto y verifica el header X-Archyl-Signature. Esto garantiza que los payloads provienen realmente de Archyl y no han sido manipulados.

Usa HTTPS

Utiliza siempre un endpoint HTTPS. Archyl no entregara webhooks a URLs HTTP sin cifrar.

Filtra por proyecto

Si tu organizacion tiene muchos proyectos, limita los webhooks a los proyectos que te interesan. Esto reduce el ruido y evita procesamiento innecesario en tu extremo.

Gestiona duplicados

En casos excepcionales (reintentos de red, failover de infraestructura), tu endpoint puede recibir el mismo evento mas de una vez. Usa los campos timestamp y event para detectar y deduplicar.

Monitoriza el estado de las entregas

Consulta la pestana de Entregas periodicamente. Un patron de fallos puede indicar problemas en el endpoint, reglas de firewall o credenciales expiradas de tu lado.

Proximos pasos

• Integraciones del Marketplace — Conecta servicios externos y muestra datos en tiempo real en tus dashboards
• Gestion de releases — Haz seguimiento de los despliegues en toda tu arquitectura
• Insights de arquitectura — Detecta problemas arquitectonicos de forma automatica