BIM y webhooks: haz que tus aplicaciones reaccionen al instante
A las 18:03 se publicó una nueva versión del modelo de instalaciones. A las 18:04 el sistema recibió dos avisos idénticos, lanzó dos validaciones y creó incidencias duplicadas. La semana anterior no había recibido ninguno porque el endpoint estuvo reiniciándose durante unos minutos. Sobre el diagrama, el flujo era instantáneo. En producción, el instante tenía reintentos, redes y cierta afición al déjà vu.
BIM y webhooks encajan bien cuando una aplicación debe reaccionar a eventos: una versión publicada, una incidencia modificada o un archivo procesado. El webhook evita preguntar continuamente si algo ha cambiado, pero no garantiza que el trabajo posterior ocurra una sola vez ni en orden. Diseñar la integración exige autenticar, persistir, deduplicar, procesar y reconciliar.
Tabla de contenidos
El evento empezó con una pregunta de proceso
El equipo quería validar cada modelo compartido para coordinación y devolver un informe. Antes, un proceso consultaba cada diez minutos si había versiones nuevas. Funcionaba, pero desperdiciaba llamadas y podía retrasar la revisión.
El webhook ofrecía un aviso cuando se publicaba una versión. Ese aviso no debía ejecutar directamente una validación de varios minutos. Su función era informar de un hecho con identificadores suficientes para recuperar contexto.
Se definió qué evento interesaba, para qué proyectos y en qué estado. Guardar cualquier cambio habría generado ruido. La integración reaccionaba a una publicación relevante, no a cada edición de metadatos.
Recibir rápido fue una decisión de arquitectura
El endpoint verificaba solicitud, extraía identificador del evento y respondía pronto. Antes de responder, persistía el mensaje de forma duradera o lo colocaba en una cola fiable. El trabajo pesado ocurría después.
Esta separación evitaba que el proveedor reintentase porque la validación tardaba demasiado. También permitía absorber picos: una entrega con muchas disciplinas podía producir varios eventos sin bloquear la recepción.
Si el mensaje no podía guardarse, el endpoint devolvía un error para favorecer el reintento según el contrato. Responder éxito antes de conservarlo habría convertido una caída local en pérdida silenciosa.
La firma demostró origen, no intención
El receptor verificaba la firma o mecanismo de autenticidad indicado por la plataforma, utilizando el cuerpo bruto y el secreto gestionado. También comprobaba marca temporal cuando existía para reducir reproducciones.
Los secretos se almacenaban fuera del código, rotaban y se separaban por entorno. Las peticiones se procesaban sobre HTTPS y los logs no mostraban credenciales ni cuerpos completos sin necesidad.
Una firma válida indicaba que el mensaje procedía del emisor esperado. No garantizaba que el proyecto perteneciese al sitio correcto o que la acción estuviese autorizada. La integración aplicaba alcance, permisos y aislamiento antes de recuperar datos.
El duplicado se trató como comportamiento normal
La mayoría de sistemas de eventos busca entregar al menos una vez. Si el receptor tarda o responde con error, puede recibir el mismo aviso. Por eso el evento incluía o generaba una clave idempotente.
Al persistir, una restricción impedía crear dos registros con la misma identidad y alcance. Si el evento ya existía, el endpoint devolvía éxito sin repetir el trabajo. Si una validación se había iniciado, el estado permitía continuar o recuperar.
La idempotencia llegaba también a los efectos. Crear un informe utilizaba versión de modelo y tipo de análisis como clave. Publicar incidencias comparaba resultados existentes. Deduplicar únicamente el mensaje no servía si el worker podía repetir la operación tras fallar.
La cola desacopló aviso y capacidad
Los workers reclamaban trabajos y limitaban concurrencia según APIs, CPU y licencias. Una ráfaga no lanzaba cuarenta descargas simultáneas. La cola conservaba estados, intentos y siguiente reintento.
Los errores transitorios —red, rate limit, servicio no disponible— se reintentaban con espera creciente y aleatoriedad. Los fallos permanentes —proyecto sin acceso, versión inexistente o configuración inválida— se detenían con una acción clara.
Después de varios intentos, el evento pasaba a una cola de errores o estado equivalente. No desaparecía. Operaciones podía inspeccionarlo, corregir la causa y reanudar de forma segura.
El webhook no llevaba todo el modelo en el bolsillo
El payload contenía referencias, no el contexto completo. El worker llamaba a la API para recuperar versión, archivo y metadatos actuales. Esto reducía tamaño y evitaba confiar en datos parciales.
Sin embargo, recuperar «lo último» podía procesar una versión distinta si llegaban eventos rápidos. El worker utilizaba el identificador exacto de la versión anunciada. La automatización respondía a ese hecho, no a una noción móvil de actualidad.
Las llamadas respetaban permisos y región. Si datos y endpoint debían permanecer en un ámbito geográfico, la arquitectura lo contemplaba. Un webhook global no justificaba transportar modelos sin revisar residencia y contratos.
El orden dejó de asumirse
Dos eventos podían llegar invertidos. Una versión posterior podía completar antes que una anterior. El sistema guardaba secuencia o marca de versión y comprobaba relevancia antes de publicar resultados.
En algunos flujos interesaba procesar todas las versiones para conservar historia. En otros, una versión superseded podía cancelarse si aún no había comenzado. La política dependía del coste y del uso.
Las incidencias no se cerraban con resultados antiguos. Cada informe declaraba la versión analizada. La interfaz mostraba si existía otra más reciente pendiente o completada.
La observabilidad siguió una historia completa
El equipo utilizó un identificador de correlación desde recepción hasta validación y publicación. Los logs permitían responder cuándo llegó el evento, qué worker lo procesó, qué API falló y qué efecto produjo.
Las métricas incluían eventos recibidos, duplicados, retraso, cola, reintentos, fallos y tiempo de proceso. Una alarma vigilaba mensajes atascados y ausencia anómala de eventos en proyectos activos.
Los dashboards no mostraban solo éxito técnico. También comprobaban que una versión publicada terminase con un informe accesible. El objetivo era el resultado editorial o BIM, no que el endpoint devolviese 200 con entusiasmo.
La reconciliación cubrió lo que el evento no pudo garantizar
Un proceso periódico consultaba versiones recientes y las comparaba con registros procesados. Si encontraba una publicación sin evento, creaba el trabajo de forma idempotente. También detectaba operaciones incompletas.
Este polling no anulaba el webhook. Actuaba como red de seguridad y reparación. Podía ejecutarse con menor frecuencia porque la reacción ordinaria era por eventos.
La combinación ofrecía baja latencia y consistencia eventual. Diseñar únicamente el camino feliz habría dejado cada caída temporal como una laguna permanente.
Webhook, API y polling ocuparon capas diferentes
| Mecanismo | Uso principal | Riesgo o coste |
|---|---|---|
| Webhook | Avisar de un cambio con baja latencia | Duplicados, pérdida aparente y orden no garantizado |
| API | Recuperar contexto y ejecutar acciones autorizadas | Límites, permisos, disponibilidad y coste de llamadas |
| Polling | Detectar estado o reconciliar huecos | Latencia y consultas innecesarias si es frecuente |
| Cola | Persistir y regular el trabajo | Operación, reintentos y supervisión |
La arquitectura no elegía un ganador. Un evento iniciaba, la API aportaba datos, la cola organizaba y el polling reparaba. Cada pieza resolvía una incertidumbre.
Los eventos evolucionaron como un contrato
El receptor toleraba campos adicionales y validaba los necesarios. Las versiones de payload se registraban. Un cambio incompatible se probaba antes de producción.
Los eventos desconocidos no se procesaban como si fueran equivalentes. Se guardaban de forma saneada y generaban una alerta. Adivinar el significado de un nuevo tipo podía disparar acciones incorrectas.
La documentación incluía ejemplos, firma, reintentos y estados. Los consumidores tenían pruebas de contrato. El webhook era una interfaz mantenida, no una URL pegada en un formulario y olvidada.
Las pruebas simularon una red poco colaboradora
El equipo envió el mismo evento varias veces, retrasó respuestas, invirtió orden y provocó fallos después de persistir pero antes de completar. También probó firmas inválidas, proyectos sin acceso y versiones borradas.
El resultado esperado incluía una sola validación efectiva y un estado recuperable. Las pruebas de integración utilizaron almacenamiento y cola reales en un entorno controlado. Los mocks ayudaban con casos unitarios, pero no demostraban locks ni reintentos.
Se ensayó la rotación de secretos y el despliegue del receptor. Una ventana de reinicio no debía perder eventos gracias a reintentos y reconciliación.
El mantenimiento apareció en cuotas y certificados
Las suscripciones podían caducar, cambiar de región o requerir renovación. El sistema supervisaba su estado. Los endpoints y certificados tenían ciclo de vida.
Las credenciales de API, límites y permisos también evolucionaban. Una integración BIM por eventos seguía siendo software en producción: necesitaba propietarios, alertas, actualizaciones y presupuesto.
Los costes se comparaban con frecuencia y urgencia. Para un evento mensual, un polling diario sencillo podía ser suficiente. Para cientos de versiones y necesidad de reacción rápida, la infraestructura de webhooks y colas se justificaba mejor.
Cuándo no usar webhooks
Si la plataforma no ofrece garantías, firma o un evento con identidad útil, quizá sea más seguro consultar estado. Si el proceso no es urgente y ocurre poco, el mantenimiento del receptor puede superar el beneficio.
Tampoco conviene ejecutar acciones irreversibles directamente desde un aviso. El webhook debe iniciar un flujo que valide contexto y permisos. Un evento no es aprobación humana.
En redes cerradas o entornos con restricciones, recibir llamadas externas puede no ser viable. La arquitectura debe respetar operación real, no forzar una moda de integración.
Reaccionar al instante fue menos importante que terminar bien
La siguiente publicación produjo dos entregas del mismo evento. El receptor guardó una, reconoció el duplicado y el worker validó exactamente la versión anunciada. El informe quedó vinculado y la reconciliación confirmó que no faltaba ninguna.
BIM y webhooks funcionan cuando el aviso forma parte de una cadena fiable. Verifica origen y alcance, persiste antes de responder, diseña idempotencia en cada efecto, regula con colas y reconcilia con la API.
Si tu arquitectura es una flecha desde «webhook» hasta «crear incidencias», todavía no está terminada. La flecha necesita varios cajones, algunos estados y, probablemente, café para quien atienda la cola de errores.
Respuestas