Webhooks: Notificaciones en Tiempo Real para Cambios en la Arquitectura
La semana pasada, un equipo me contó que habían renombrado un sistema central en Archyl: cambiaron "UserService" a "AccountService" en todo el modelo C4, actualizaron las relaciones y reescribieron el ADR. Un trabajo limpio y exhaustivo. El problema fue que el equipo de plataforma que dependía de ese sistema se enteró cuatro días después, cuando su pipeline de despliegue hacía referencia a un nombre que ya no existía.
Nadie les avisó. No porque alguien fuera descuidado, simplemente no existía un mecanismo para hacerlo. La documentación de arquitectura suele funcionar con un modelo pull. Vas a ver el diagrama. Vas a leer el ADR. Si no vas a mirar, no te enteras.
Es el mismo patrón que afectaba al desarrollo de software antes de que las notificaciones de CI/CD se convirtieran en estándar. Los cambios de código solían ser algo que descubrías al hacer pull de main. Hoy en día, cada merge, cada build fallido, cada despliegue dispara una notificación en algún lugar. Los cambios de arquitectura merecen el mismo tratamiento.
Notificaciones Push para Tu Arquitectura
Archyl ahora soporta webhooks. Cuando algo cambia en tu modelo C4 (se crea un sistema, se elimina un contenedor, se actualiza una relación, se despliega un release), Archyl envía un HTTP POST a cualquier endpoint que configures, con un payload JSON que describe exactamente lo que ocurrió.
La idea es sencilla: tu arquitectura es un sistema vivo. Las personas y las herramientas deberían poder suscribirse a sus cambios de la misma forma en que se suscriben a eventos de despliegue o notificaciones de pull requests. En lugar de preguntar "¿cambió algo?", la respuesta llega a ti.
44 Tipos de Eventos
No queríamos lanzar un sistema de notificaciones que cubriera solo la mitad del modelo. Los webhooks se disparan en todo lo que Archyl rastrea:
Elementos C4 — Creación, actualización y eliminación de sistemas, contenedores, componentes y elementos de código. El núcleo de tu modelo de arquitectura.
Relaciones — Cuando se crean, modifican o eliminan conexiones entre elementos. Esta suele ser la señal más importante: una nueva dependencia entre dos sistemas es el tipo de cambio que múltiples equipos necesitan conocer.
ADRs y Documentación — Registros de Decisiones de Arquitectura y documentación de proyecto que se crean, actualizan o eliminan. Cuando alguien escribe un nuevo ADR explicando por qué el equipo está migrando de REST a gRPC, las personas afectadas deberían enterarse de inmediato, no tres sprints después.
Flujos — Cambios en flujos de usuario y de sistema. Nuevos flujos, pasos actualizados, flujos eliminados.
Overlays — Cambios en las agrupaciones visuales de tus diagramas.
Releases — Eventos de despliegue en distintos entornos. Combinado con la gestión de releases, esto te da un pipeline completo de notificaciones de despliegue basado en push.
Solicitudes — Solicitudes de cambio de arquitectura que se abren, revisan o fusionan.
Contratos de API y Canales de Eventos — Cambios en especificaciones y actualizaciones de mensajería asíncrona vinculadas a tu arquitectura.
Descubrimiento e Insights — Descubrimientos completados con IA y nuevos insights de arquitectura.
Cuarenta y cuatro tipos de eventos en total. Tú eliges los que te importan: suscríbete a todo, o solo a los cinco eventos que son relevantes para tu flujo de trabajo.
Cómo Funciona
Configurar un webhook toma unos treinta segundos.
Le das un nombre (algo descriptivo: "Notificaciones de Slack", "Sincronización de log de auditoría", "Trigger de CI"). Proporcionas una URL, cualquier endpoint HTTP que pueda recibir una solicitud POST. Opcionalmente estableces un secreto para la verificación de firma. Luego seleccionas qué eventos deben activarlo.
También puedes limitar un webhook a proyectos específicos. Un webhook a nivel de organización que se dispara con cada cambio en todos los proyectos es útil para el registro de auditoría. Un webhook limitado a un proyecto que solo se dispara con eventos de release de tu sistema de pagos es útil para el equipo que lo gestiona.
Cuando ocurre un evento coincidente, Archyl envía un HTTP POST a tu URL con un payload JSON que contiene:
- Tipo de evento — Cuál de los 44 eventos activó esta entrega
- Entidad — Los detalles completos del elemento que cambió
- Actor — Quién realizó el cambio (ID de usuario, nombre, email)
- Proyecto — En qué proyecto ocurrió
- Timestamp — Cuándo ocurrió el cambio
- Organización — A qué organización pertenece
El payload te da todo lo que necesitas para reaccionar al cambio: mostrarlo, registrarlo, disparar un pipeline o sincronizarlo con otro sistema.
Seguridad: Firmas HMAC-SHA256
Cada solicitud de webhook incluye un header X-Archyl-Signature con el formato sha256=<hex digest>, un hash HMAC-SHA256 del cuerpo crudo de la solicitud, calculado usando tu secreto. También recibirás X-Archyl-Event (el tipo de evento) y User-Agent: Archyl-Webhook/1.0 para que puedas identificar el origen.
En el lado receptor, eliminas el prefijo sha256=, recalculas el hash HMAC-SHA256 con tu copia del secreto contra los bytes crudos del cuerpo, y comparas utilizando comparación en tiempo constante. Si coinciden, la solicitud es auténtica. Si no, alguien te está enviando eventos falsificados.
Este es el mismo esquema de firma utilizado por GitHub, Stripe y la mayoría de los proveedores de webhooks. Es simple, bien conocido y fácil de implementar en cualquier lenguaje. Sin flujos OAuth, sin rotación de tokens, sin gestión de certificados. Solo un secreto compartido y un hash. Consulta la documentación de webhooks para ver ejemplos completos de verificación en Go, Node.js y Python.
Si no configuras un secreto, el header de firma se omite. Está bien para endpoints internos detrás de una VPN. No se recomienda para nada expuesto a internet.
Qué Puedes Construir con Esto
El caso de uso más obvio son las notificaciones en chat. Slack, Microsoft Teams y Discord soportan webhooks entrantes: pega su URL en Archyl, selecciona los eventos que te interesan, y los cambios de arquitectura empezarán a aparecer en tu canal. Se agregó un nuevo sistema. Un ADR fue aprobado. Un release se desplegó a producción. Tu equipo lo ve sin necesidad de abrir Archyl.
Pero las notificaciones son solo el principio.
Sincronización con sistemas externos — Envía cambios de arquitectura a un CMDB, una wiki interna o un catálogo de servicios. Cuando se renombra un contenedor en Archyl, tu catálogo de servicios se actualiza automáticamente.
Disparar pipelines de CI/CD — Cuando se fusiona una solicitud de cambio de arquitectura, lanza un pipeline que regenere la configuración de infraestructura, actualice módulos de Terraform o valide que el despliegue real coincide con la arquitectura documentada.
Pista de auditoría — Reenvía cada evento a un sistema de logging externo: Elasticsearch, Splunk, una base de datos simple de solo escritura. Siete días de historial de entregas en Archyl son útiles para depuración; un log externo permanente es útil para cumplimiento normativo.
Dashboards personalizados — Construye un dashboard interno que reaccione a eventos de arquitectura en tiempo real. Rastrea con qué frecuencia cambia la arquitectura, qué equipos son más activos y qué sistemas son más volátiles.
El punto es que los webhooks convierten a Archyl en una fuente de eventos. Tu modelo de arquitectura se convierte en algo a lo que otros sistemas pueden suscribirse, reaccionar y construir sobre ello.
Seguimiento de Entregas
Cada entrega de webhook queda registrada. Puedes ver el historial completo de cualquier webhook: qué evento lo activó, el payload de la solicitud que se envió, el código de estado de la respuesta, el cuerpo de la respuesta y las marcas de tiempo de cuándo se envió y cuándo llegó la respuesta.
Las entregas se conservan durante siete días. Suficiente tiempo para depurar problemas de integración, y lo bastante corto para no almacenar los cuerpos de respuesta de tu endpoint indefinidamente.
Cuando una entrega falla (un 500 de tu servidor, un timeout, un error de resolución DNS), aparece con un estado en rojo. Puedes inspeccionar el error, corregir tu endpoint y reintentar con un solo clic. El reintento envía exactamente el mismo payload, para que tu endpoint procese el evento original como si hubiera tenido éxito la primera vez.
Sin reintentos automáticos. Consideramos el backoff exponencial, pero en la práctica, la mayoría de los fallos de webhooks son transitorios (tu servidor se estaba reiniciando) o estructurales (la URL es incorrecta). Para los fallos transitorios, el botón de reintento manual es más rápido que esperar el backoff. Para los fallos estructurales, los reintentos automáticos solo generan ruido.
Primeros Pasos
- Ve a Configuración de Organización > Webhooks
- Haz clic en Crear Webhook
- Ingresa un nombre, pega la URL de tu endpoint y establece un secreto
- Selecciona los eventos a los que quieres suscribirte
- Opcionalmente filtra por proyectos específicos
- Haz clic en Enviar Prueba para verificar que tu endpoint recibe el payload
- Guarda, y ya estás en producción
La entrega de prueba envía un evento ping con un payload de ejemplo para que puedas confirmar que tu endpoint es accesible, que tu secreto está configurado correctamente y que tu handler procesa el JSON como se espera. Haz esto antes de suscribirte a eventos reales.
La Arquitectura como Flujo de Eventos
Hemos estado construyendo hacia una versión de la documentación de arquitectura que no sea un artefacto estático, sino una parte viva y conectada de tu flujo de trabajo de desarrollo. Las Integraciones del Marketplace traen datos externos hacia tu arquitectura. Los webhooks envían datos de arquitectura hacia tus herramientas.
La combinación es poderosa. Tu espacio de trabajo de arquitectura no es solo un lugar al que vas a mirar diagramas. Es un hub que recibe datos operativos de tus herramientas de monitoreo y emite eventos de cambio hacia tus herramientas de comunicación y automatización. Los datos fluyen en ambas direcciones.
La documentación de arquitectura que nadie consulta es inútil. La documentación de arquitectura que te notifica cuando importa, eso es infraestructura.
Quieres ver cómo otras funcionalidades conectan tu arquitectura con tu flujo de trabajo? Consulta Integraciones del Marketplace para traer datos en vivo a tus diagramas, o Gestión de Releases para rastrear despliegues en tu modelo C4.