Data Management webhooks: sincroniza sin perder eventos por el camino
El dashboard mostraba que el modelo de arquitectura estaba actualizado. La validación nocturna, sin embargo, había procesado el archivo de la semana anterior. La integración había detectado un elemento llamado «ARQ_Modelo.rvt» y lo había marcado como sincronizado, pero no había distinguido entre el documento lógico y la nueva versión publicada. Todo estaba verde excepto el dato importante.
Los Data Management webhooks resultan útiles para reaccionar a cambios en proyectos, carpetas, ítems y versiones de un sistema documental. El reto no es solo recibir eventos. Es entender qué recurso ha cambiado, recuperar su estado exacto y mantener una réplica coherente aunque los avisos lleguen duplicados, desordenados o falten. En este artículo el webhook es una pieza del ciclo documental, no una definición con flechas.
Tabla de contenidos
La réplica empezó dibujando la jerarquía
El sistema externo tenía proyectos, carpetas, ítems y versiones. Una carpeta organizaba; un ítem representaba el documento a lo largo del tiempo; cada versión era un artefacto concreto. La réplica había guardado nombre y URL, información insuficiente para seguir la historia.
El equipo añadió identificadores externos, relaciones y versión. El modelo local distinguía proyecto, carpeta, ítem y versión. Una validación se vinculaba a la versión exacta. El estado «actualizado» se calculaba comparando referencias, no nombres.
Esta estructura permitió responder qué se había procesado y qué versión era la más reciente conocida. También mostró que mover un ítem entre carpetas no equivalía a crear otro documento.
El alcance de la suscripción se eligió con cuidado
Suscribirse a todos los eventos de toda la cuenta habría simplificado configuración y multiplicado ruido. El equipo identificó proyectos y tipos de evento relevantes: nuevas versiones en carpetas compartidas para coordinación.
La suscripción conservaba scope, región, callback, estado y propietario. Los permisos del creador y las capacidades vigentes se verificaban. Si el proyecto cambiaba de etapa o se archivaba, la suscripción se retiraba.
El alcance se documentó. Recibir un evento no implicaba poder descargar el recurso; la credencial de procesamiento necesitaba acceso. Suscripción y autorización eran contratos relacionados, no idénticos.
El receptor guardó el aviso antes de interpretarlo
La petición se autenticaba según el mecanismo soportado, se vinculaba con una suscripción conocida y se persistía. El endpoint respondía rápido. Un worker interpretaba el recurso y consultaba la API.
Guardar el payload bruto completo indefinidamente no era necesario. Se conservaban campos, hash y contexto suficientes, con una copia temporal saneada para diagnóstico cuando correspondía.
Si el evento no podía persistirse, se devolvía error. Si ya existía, se reconocía sin repetir. El receptor no abría archivos ni lanzaba validaciones dentro del tiempo de respuesta.
El evento identificó un cambio, no el estado completo
El payload podía indicar recurso y tipo, pero la réplica consultaba proyecto, ítem o versión exacta. La API era la fuente para completar metadatos y relaciones.
El worker no pedía únicamente «la versión más reciente» si el evento se refería a otra. Guardaba la anunciada y después calculaba cuál era la última conocida. Esto permitía reconstruir historia aunque los eventos llegasen fuera de orden.
Si el recurso ya no existía o el acceso se había retirado, el estado reflejaba la condición. No borraba inmediatamente la réplica y sus informes; aplicaba la política de retención y marcaba la pérdida de acceso.
Una nueva versión no creó un nuevo documento
El ítem conservaba identidad y acumulaba versiones. El dashboard mostraba la última publicada, la última sincronizada y la última validada. Podían ser distintas durante el procesamiento.
Los informes antiguos seguían vinculados con su versión. Cuando llegaba otra, se creaba un trabajo independiente e idempotente. Cerrar incidencias sobre una versión nueva requería comparar resultados, no mover el enlace del informe anterior.
Los nombres podían cambiar. La réplica actualizaba el nombre del ítem sin perder su historia. Usar la ruta como clave habría tratado cada renombrado como desaparición y nacimiento.
Los movimientos de carpeta conservaron significado
Un documento podía pasar de trabajo en curso a compartido o publicado mediante movimiento o cambio de estado, según el flujo. La réplica actualizaba la relación y evaluaba si el nuevo contexto activaba una validación.
No todos los movimientos eran equivalentes a una aprobación. El proceso editorial definía qué carpeta o estado tenía ese significado. La plataforma aportaba el evento; el proyecto aportaba la regla.
Si una carpeta se renombraba, los descendientes no se recreaban. La sincronización utilizaba IDs y actualizaba rutas derivadas. Este detalle evitó una tormenta de falsos cambios.
La idempotencia llegó hasta la validación
La clave incluía proyecto, versión y tipo de proceso. Dos eventos de la misma versión producían un solo trabajo efectivo. Si el worker fallaba después de descargar pero antes de guardar resultado, podía reanudar.
Los efectos externos también se protegían. Publicar un informe o crear incidencias utilizaba claves estables y comparaba el estado previo. La entrega repetida del webhook no duplicaba el tablero.
La base de datos aplicaba restricciones, no solo comprobaciones en memoria. Dos workers concurrentes podían recibir el mismo evento; uno debía ganar sin que ambos creyesen ser originales.
El orden se resolvió con versiones, no con confianza
La versión 18 podía llegar antes que la 17. La réplica guardaba ambas y calculaba orden mediante metadatos fiables. Si la 17 ya no aportaba valor operativo, su validación podía omitirse según política, pero su existencia quedaba registrada.
Una validación antigua nunca sobrescribía el estado de la última. Los resultados mostraban su versión. La interfaz advertía cuando el usuario consultaba un artefacto superseded.
La fecha de recepción no determinaba por sí sola el orden documental. Las redes son excelentes transportando datos y bastante indiferentes a nuestra narrativa.
La reconciliación recorrió proyectos y carpetas
Periódicamente, un proceso listaba proyectos activos, carpetas de alcance, ítems y versiones recientes. Comparaba con la réplica y creaba trabajos faltantes. También detectaba recursos locales cuyo acceso había cambiado.
La reconciliación paginaba, respetaba límites y guardaba cursores. No descargaba todos los archivos; consultaba metadatos y profundizaba donde encontraba diferencias.
Este barrido permitía reparar eventos perdidos, suscripciones caídas y despliegues. El webhook daba rapidez; el inventario periódico daba confianza.
Las suscripciones tuvieron ciclo de vida
El equipo supervisaba creación, renovación, región y callback. Una suscripción huérfana podía dejar de enviar sin que el dashboard documental lo notase de inmediato.
Las credenciales y secretos rotaban. Los callbacks antiguos se retiraban tras el despliegue. Los entornos de pruebas utilizaban proyectos aislados y no recibían eventos de producción.
Una alerta comparaba actividad esperada y recibida. El silencio no siempre era fallo, pero un proyecto con publicaciones y cero eventos necesitaba investigación.
La región afectó a más que una URL
Proyectos, endpoints y suscripciones debían utilizar la región correcta. Los IDs y rutas se manejaban según el contrato actual. La réplica guardaba región para dirigir llamadas.
Los datos no se copiaban entre regiones por comodidad. La arquitectura respetaba residencia y permisos. Los procesos y logs se desplegaban con esas restricciones.
La configuración se probaba por región. Asumir que cambiar un hostname resolvía todo habría sido una forma rápida de conocer varios errores 404.
El dashboard mostró estados que las personas podían interpretar
Para cada ítem aparecían versión remota conocida, sincronizada, procesada y con error. Un retraso en la cola no se presentaba como desactualización misteriosa.
Los usuarios podían reintentar fallos seguros o solicitar acceso. Operaciones veía el evento y la correlación. La interfaz no mostraba detalles sensibles del proveedor.
La fecha de última reconciliación aportaba contexto. «Sin cambios» significaba comprobado hasta un momento concreto, no confianza eterna.
Las pruebas reprodujeron una carpeta poco obediente
El equipo creó versiones rápidas, renombró ítems, movió carpetas, duplicó eventos y retiró permisos. También detuvo el receptor y comprobó la reparación posterior.
Las pruebas de integración usaban un proyecto real aislado. Las unitarias validaban transición de estados y deduplicación. La base de datos real demostraba restricciones concurrentes.
Actualizar API o scopes activaba el conjunto. La documentación oficial se revisaba porque eventos, límites y contratos podían evolucionar.
Los límites del espejo se documentaron
La réplica no copiaba cada propiedad ni sustituía el sistema documental. Conservaba lo necesario para el proceso de validación y trazabilidad. Los archivos se descargaban cuando había trabajo y se retenían según política.
Los permisos remotos seguían gobernando acceso al origen. La aplicación local no debía convertirse en atajo para usuarios que habían perdido acceso.
Si el proceso solo necesitaba consultar una versión ocasional, mantener este espejo podía ser excesivo. El valor aparecía con volumen, automatización y necesidad de reconstruir historia.
Cuándo el polling puede bastar
Un proyecto pequeño con pocas publicaciones podía consultarse cada cierto tiempo. La implementación era más simple y quizá suficiente. El coste dependía de frecuencia y límites.
Los webhooks ganaban cuando la reacción rápida y el volumen justificaban receptor y cola. Incluso entonces, el polling de reconciliación seguía siendo útil.
La decisión no debía partir de que «los eventos son modernos». Debía comparar latencia, capacidad de reparación, operación y coste.
Sincronizar significó saber exactamente qué faltaba
Tras el rediseño, el dashboard distinguió el ítem de sus versiones. La validación del lunes quedó vinculada con la versión correcta, y una publicación perdida durante un despliegue apareció en la reconciliación.
Diseñar Data Management webhooks fiables exige modelar la jerarquía documental, persistir eventos, deduplicar efectos, respetar orden y mantener suscripciones. La API confirma el estado y el barrido periódico repara.
Si tu réplica solo guarda «nombre del archivo» y «actualizado: sí», no está sincronizada: está siendo optimista. Añade una versión antes de que el siguiente modelo conserve el mismo nombre por pura tradición.
Respuestas