BIM y webhooks: del aviso al trabajo completado

Entre «archivo actualizado» e «informe disponible» cabe una flecha preciosa. También caben una caída de red, dos notificaciones repetidas y un proceso que se detiene después de guardar la mitad del trabajo. Los diagramas tienen esa ventaja sobre la producción: nunca se les reinicia el servidor. Un webhook permite reaccionar a un cambio; vamos a ocuparnos de lo que la flecha suele ocultar antes de anunciar que las aplicaciones ya se entienden solas.

BIM y webhooks pueden conectar ese cambio con una aplicación que deba reaccionar. Un webhook es, de forma sencilla, un aviso que un servicio envía a una dirección de tu aplicación cuando ocurre un evento al que te has suscrito. Vamos a seguir un ejemplo hipotético: preparar un informe cuando aparece una versión relevante para coordinación. El recorrido ayudará a distinguir recibir una notificación de completar el trabajo que prometemos al equipo.

Empieza por el cambio que importa al proceso

La presentación de la Webhooks API de Autodesk explica que puedes suscribirte a tipos de eventos y recursos para recibir notificaciones en una URL. La lista disponible depende del servicio y de su contrato. Antes de elegir un evento, concreta qué significa para tu proceso: que haya una nueva versión no demuestra por sí solo que el equipo la considere lista para coordinación.

Imagina que el informe debe prepararse sobre archivos de una carpeta compartida y que otras carpetas contienen trabajo en curso. Suscribirse a cualquier modificación de todo el proyecto introduciría avisos que la aplicación tendría que descartar después. Define el recurso vigilado y la condición de relevancia. Un evento técnicamente válido puede estar fuera del encargo; por eso la recepción debe conservar suficiente contexto para decidir qué corresponde procesar.

Tampoco todos los cambios disponen de un webhook adecuado. Si la plataforma no ofrece la notificación que necesitas, puede ser necesario consultar su API de forma periódica o combinar ambas estrategias. Revisar cada cierto tiempo es lo que suele llamarse polling. Tiene costes y latencia, pero puede ser una solución perfectamente razonable para una tarea poco urgente. Un sistema no se vuelve anticuado por seguir funcionando con una arquitectura más sencilla.

Para el ejemplo, el aviso iniciaría una solicitud de análisis vinculada a una versión concreta. La aplicación tendría que recuperar información con los permisos necesarios y preparar el informe. La notificación no necesita transportar todo el modelo ni resolver la validación. Su trabajo es comunicar un hecho que podamos relacionar con una tarea, algo menos espectacular que «integración instantánea», aunque bastante más preciso.

Escribe también qué resultado verá la persona: informe pendiente, completado o con un problema que requiere atención. Si solo muestras que llegó un aviso, el usuario todavía no sabe si se analizó su archivo. Esta diferencia orienta desde el principio qué identificadores, estados y mensajes necesitará la solución. Ahorrarse esa definición deja una flecha muy limpia en la presentación y una conversación bastante menos limpia al final de la entrega.

Recibir el aviso es una operación breve y verificable

El receptor es la dirección de tu aplicación a la que el proveedor envía la solicitud. Debería comprobar el formato, verificar su autenticidad según el mecanismo documentado y relacionarla con una suscripción y un alcance conocidos. Que una URL sea difícil de adivinar no sustituye esa verificación. Si el proveedor permite firmar mensajes con un secreto, hay que configurar y comprobar ese mecanismo en el entorno real.

Autodesk explica la verificación de firmas en un ejemplo para Python. Un detalle importante es conservar la representación del mensaje que exige la verificación: interpretar y volver a serializar un JSON puede cambiar los bytes utilizados al calcular una firma. La explicación de Autodesk sobre el cuerpo de la solicitud muestra precisamente ese tipo de error. El algoritmo y el formato deben tomarse del contrato del servicio, no de una receta genérica que encontraste para otro proveedor.

Superada esa comprobación, el receptor debe conservar duraderamente lo necesario para procesar el aviso antes de responder que lo ha aceptado. Puede registrar un trabajo en una base de datos o entregarlo a una cola con garantías conocidas. El análisis pesado vendría después. Si la operación tarda minutos, mantener abierta la petición mientras descargas y revisas el modelo mezcla disponibilidad del receptor con duración del trabajo.

Aquí aparece una decisión que suele quedar oculta: qué significa la respuesta de éxito. Si responde correctamente y se reinicia antes de guardar, puede haber confirmado un mensaje que ya no podrá recuperar. Si no consigue conservarlo, debe responder conforme al contrato de errores del proveedor, de manera que pueda intervenir su mecanismo de entrega. Conviene conocer los plazos y condiciones concretas de reintento; «ya lo reenviará» es una expectativa, todavía no una estrategia.

Una firma válida tampoco autoriza cualquier acción posterior. Debes comprobar que el recurso pertenece al entorno que atiende la aplicación y que la identidad de integración tiene el acceso necesario. El secreto del webhook, la credencial de la API y la autorización para modificar datos cumplen funciones diferentes. Mezclarlos puede hacer que un mensaje auténtico desencadene una operación fuera del alcance previsto, un resultado bastante incómodo para una comprobación que figuraba en verde.

Los duplicados y las versiones necesitan una política explícita

Imagina que recibes dos notificaciones relacionadas con la misma versión. Antes de lanzar dos análisis hay que determinar qué identidad ofrece el servicio y qué trabajo debe considerarse equivalente. Un identificador de entrega puede ayudar a reconocer una recepción, mientras la versión del modelo y el tipo de análisis pueden identificar el resultado que quieres producir. Son niveles diferentes: recibir un mensaje una vez no garantiza que un proceso nunca vuelva a ejecutarse.

Diseñar una operación idempotente significa que repetir la misma solicitud no multiplique el efecto que debía tener. Para nuestro caso, registrar la intención de analizar una versión con una regla concreta permitiría reconocer trabajo pendiente o ya terminado. Esa decisión necesita una protección real frente a peticiones simultáneas; una consulta previa sin una condición de unicidad puede dejar pasar dos procesos al mismo tiempo. El mecanismo concreto depende del almacenamiento elegido.

El problema continúa en los efectos. Un proceso puede crear el informe y fallar antes de marcarlo como completado. Cuando se recupere, debería poder localizar ese resultado en vez de generar otro o publicar incidencias duplicadas. Por eso conviene relacionar informe, versión y regla de análisis. La idempotencia debe alcanzar las operaciones que importan al usuario, no quedarse en una comprobación superficial del primer mensaje recibido.

Ahora imagina que llegan avisos de dos versiones y la más antigua termina de analizarse después. Si tu interfaz sustituye siempre el informe por el último proceso que acaba, podría presentar datos atrasados como actuales. Conserva la versión analizada y define si deben procesarse todas, si una puede quedar pendiente o si determinados trabajos se pueden descartar antes de empezar. La política tiene que responder al uso del informe; el orden de llegada no debería decidirlo accidentalmente.

Nada de esto exige prometer que el trabajo ocurrirá exactamente una vez en cualquier circunstancia. Exige explicar qué repeticiones pueden ocurrir y cómo evita la aplicación multiplicar sus consecuencias. Esa afirmación más concreta se puede comprobar. «No habrá duplicados» sin describir de qué operación hablamos suele funcionar muy bien hasta el primer fallo entre dos guardados.

Una cola organiza el trabajo y la recuperación evita los silencios

Una cola permite separar los avisos recibidos de la capacidad disponible para analizarlos. En una entrega con varias disciplinas puede haber una ráfaga de nuevas versiones. Los procesos de trabajo, o workers, pueden ir recuperando tareas con una concurrencia limitada para no descargar ni consultar todo al mismo tiempo. La cola necesita estados comprensibles, intentos y una forma de detectar trabajos que han quedado a medias.

No todos los fallos merecen la misma respuesta. Un problema temporal de red puede justificar reintentar con una espera creciente; un permiso revocado puede requerir intervención. La clasificación debe basarse en la respuesta documentada de la operación y admitir cambios cuando la condición pueda recuperarse. Repetir indefinidamente una petición que no puede funcionar solo convierte un error en una actividad programada.

Después de varios intentos, conserva el trabajo en un estado visible con su motivo y la acción que permitiría retomarlo. El usuario necesita saber qué informe falta y sobre qué versión. Quien mantiene el sistema necesita seguir la relación entre recepción, descarga, análisis y publicación. Un identificador común para ese recorrido ayuda a localizar la causa sin buscar por fechas aproximadas entre registros de servicios distintos.

El webhook no debería ser la única forma de descubrir que falta trabajo. Una reconciliación periódica puede consultar versiones relevantes mediante la API y compararlas con los análisis registrados. Si detecta una ausencia, genera o recupera la tarea aplicando la misma política de repetición. Esta es una propuesta de arquitectura para el ejemplo: su frecuencia y alcance deben ajustarse a cuotas, volumen y necesidad de reacción.

También hay que vigilar la suscripción y sus condiciones de entrega. La información oficial de Webhooks de Autodesk enlaza las garantías de entrega y la guía de campos, incluidos mecanismos de reintento y reactivación. La integración debe basarse en esa documentación vigente. Un receptor encendido no demuestra que una suscripción siga enviándole los cambios que el equipo espera recibir.

Comprueba el recorrido completo antes de llamarlo automático

La prueba útil empieza con un evento conocido y termina localizando un informe asociado a su versión. Entre medias, comprueba un duplicado, un mensaje inválido y un fallo después de registrar la tarea. Añade una interrupción tras producir el resultado pero antes de confirmar el trabajo: ese punto suele revelar si el sistema puede recuperarse sin repetir efectos. Un simulador ayuda con casos pequeños, pero no demuestra por sí solo el comportamiento de una cola o una base de datos reales.

Prueba también que una versión anterior no sustituya de forma engañosa el resultado actual y que los casos sin acceso queden explicados. Cuando cambies secretos, despliegues el receptor o actualices el procesamiento, el equipo debe poder distinguir trabajo pendiente de trabajo perdido. El resultado esperado de cada ensayo tiene que estar escrito antes de ejecutarlo; de lo contrario, siempre habrá una forma creativa de interpretar la salida como un éxito.

La operación necesita un responsable, registros útiles y una política de conservación que evite almacenar secretos o modelos completos por comodidad. Si el proceso ocurre una vez al mes y admite demora, quizá una consulta periódica sea más barata de mantener. Si exige reaccionar con frecuencia y rapidez, un flujo por eventos puede compensar. El coste incluye atender sus excepciones, no solo hospedar una URL.

El ejemplo de este artículo describe decisiones para diseñar y probar la integración; no acredita una implantación ejecutada. Lo que merece la etiqueta de automático es un recorrido capaz de terminar y explicar lo que falta, incluso cuando recibe un aviso repetido o se reinicia una pieza. Recibir una petición y devolver un 200 es un comienzo respetable. Todavía queda un informe por entregar.

El webhook útil inicia un trabajo que puedes identificar, recuperar y comprobar, incluso cuando el aviso llega dos veces. Antes de conectarlo a una acción importante, prueba un fallo entre dos pasos y explica cómo se retoma. Si la única recuperación consiste en llamar al autor y decirle «vuelve a lanzarlo», habéis diseñado una notificación con asistencia telefónica, no un flujo fiable.