Formularios HubSpot Legacy vs V4: qué cambia al personalizarlos en WordPress

Cuando un formulario de HubSpot no encaja con el diseño de tu web

Has preparado una landing en WordPress, tienes el diseño bien trabajado y solo falta insertar el formulario de HubSpot. Copias el código, lo pegas en la página y el formulario aparece. Hasta aquí, todo parece ir bien.

El susto viene después.

Cuando intentas ajustarlo al estilo real de la web, empiezan los detalles: el botón no se comporta como el resto de llamadas a la acción, los campos no responden a los estilos como esperabas o ese pequeño snippet que antes añadía una clase, rellenaba un campo oculto o lanzaba un evento ya no funciona igual.

Esto no significa que el formulario no se pueda personalizar. Significa que no todos los formularios de HubSpot se integran con las mismas reglas. Los formularios Legacy y los formularios V4 pueden adaptarse a una web WordPress, pero la forma de trabajar su HTML, su CSS y sus eventos JavaScript cambia.

Y ese cambio importa porque el formulario no es un adorno. Muchas veces es el punto donde una visita pide información, solicita una demo o se convierte en oportunidad comercial. Por eso no basta con que cargue: tiene que encajar, comportarse bien y enviar los datos correctos.

La cuestión no es si V4 se puede personalizar. Sí se puede. La cuestión es cómo hacerlo bien sin arrastrar código pensado para Legacy. Porque en captación, copiar, pegar y cruzar los dedos no debería ser una estrategia.

Esta versión mantiene la idea, pero va más al grano. Y dejamos para el siguiente apartado la explicación de por qué conviene hablar de Legacy y V4 en lugar de antiguo/nuevo.

Legacy y V4: mejor llamarlos por su nombre

Cuando hablamos de formularios “antiguos” y “nuevos” de HubSpot, nos entendemos rápido, pero no es la forma más precisa de plantearlo. Nuevo y antiguo dependen demasiado del momento en que leas el artículo.

Por eso es mejor usar los nombres reales: Legacy y V4.

Los Legacy forms son los formularios creados con el editor anterior de HubSpot. Los Forms V4 pertenecen al editor actualizado. Ambos pueden integrarse y personalizarse en una web externa, pero no se trabajan exactamente igual.

Esta diferencia importa especialmente en WordPress. Dos formularios pueden tener los mismos campos, el mismo texto legal y el mismo botón, pero generar una estructura distinta por debajo. Y si cambia esa base, también cambia la forma de aplicar estilos, escuchar eventos o modificar comportamientos con JavaScript.

En la práctica, antes de pedir “cambia este formulario por el nuevo”, merece la pena comprobar qué tipo de formulario es y cómo está integrado. Si el formulario anterior dependía de raw HTML, clases personalizadas, eventos propios o ajustes finos desde el tema de WordPress, pasar a V4 no debería tratarse como un simple reemplazo.

La buena noticia es que V4 también se puede personalizar. La diferencia está en que hay que hacerlo con su propio enfoque, no esperando que responda como un formulario Legacy.

Qué permitían los formularios Legacy con raw HTML

Una de las grandes ventajas de los formularios Legacy de HubSpot era la opción Set as raw HTML form. Permitía que el formulario se renderizarse como HTML dentro de la propia página, en lugar de hacerlo dentro de un iframe.

Para una web en WordPress, esto era muy cómodo. El equipo técnico podía aplicar estilos desde la hoja CSS del tema, ajustar clases, igualar el botón con el resto de llamadas a la acción o modificar pequeños detalles para que el formulario pareciera parte real de la web.

Pero el valor no estaba solo en el diseño. Al tener más acceso al formulario y a sus eventos, también era más sencillo trabajar con JavaScript: preparar campos ocultos, enviar eventos a dataLayer, capturar la URL de origen o activar una conversión cuando el envío se completaba.

Un ejemplo típico en formularios Legacy podía ser este:

hbspt.forms.create({
    region: 'na1',
    portalId: 'XXXX',
    formId: 'YYYY',
    onFormReady: function(form) {
        // El formulario ya está cargado.
        // Aquí podíamos añadir clases, preparar campos ocultos
        // o adaptar pequeños detalles visuales.
    },
    onFormSubmitted: function(form) {
        // El envío se ha completado.
        // Aquí podíamos lanzar eventos de conversión o avisar a GTM.
        window.dataLayer = window.dataLayer || [];
        window.dataLayer.push({
            event: 'hubspot_form_success',
            formId: 'YYYY'
        });
    }
});

Esto hacía que muchas integraciones fueran fáciles de mantener. Si necesitabas guardar una UTM, añadir una clase al botón o avisar a Google Tag Manager, podías hacerlo desde el propio código de integración.

Este tipo de control no es exclusivo de WordPress. En Bubuku ya hemos tratado un caso parecido al explicar cómo integrar formularios de HubSpot en Webflow, donde también aparece el mismo equilibrio entre autonomía de marketing, diseño y control técnico.

El punto importante es este: raw HTML no era solo una opción para “poner bonito” un formulario. Permitía controlar mejor su aspecto, su comportamiento y los datos que se movían alrededor de la conversión.

Qué cambia en los formularios V4 al integrarlos en WordPress

Con los formularios V4, HubSpot cambia el enfoque. No significa que ya no se puedan personalizar con CSS o JavaScript. Sí se puede. De hecho, en Bubuku I Code ya lo hemos hecho en proyectos reales.

La diferencia es que no conviene tratarlos como si fueran formularios Legacy. Cambia la estructura que genera HubSpot, pueden cambiar los nombres de clases y también cambia la forma recomendada de trabajar con eventos.

V4 puede aportar ventajas interesantes para marketing: más autonomía dentro de HubSpot, una experiencia de edición más actual y opciones para crear formularios más dinámicos. Por ejemplo, mostrar campos distintos según la respuesta del usuario, el tipo de email o determinadas condiciones del propio formulario.

Aquí aparece una duda razonable para cualquier responsable de marketing: si el formulario actual está en Legacy y funciona bien, ¿conviene migrarlo por miedo a que quede deprecated? Y, al mismo tiempo, si V4 ofrece funcionalidades nuevas útiles para captación, ¿tiene sentido quedarse quietos?

La respuesta no debería ser migrar deprisa por miedo, ni quedarse en Legacy por costumbre. Lo sensato es evaluar cada formulario según su impacto real: qué páginas generan más leads, qué personalizaciones dependen del sistema actual y qué funcionalidades de V4 aportan valor de verdad.

Por qué el CSS y el HTML ya no se trabajan igual

El cambio más visible está en la estructura que genera HubSpot. Con un formulario Legacy en raw HTML, el equipo técnico podía trabajar sobre una estructura más directa desde la propia página: inspeccionar el formulario, aplicar selectores CSS, ajustar clases y hacer que campos, botones o mensajes encajasen con el tema de WordPress.

Con V4, la personalización sigue siendo posible, pero hay que revisar la estructura real que se está generando. No conviene asumir que los selectores, clases o jerarquías serán equivalentes a las de Legacy.

Por ejemplo, si en una web tenías estilos preparados para labels, errores, botones o mensajes de confirmación sobre un formulario Legacy, es posible que no sirvan tal cual en V4. No porque V4 no se pueda personalizar, sino porque necesita su propio CSS.

Aquí es donde muchas migraciones se complican: el formulario carga, pero el botón ya no encaja, los espacios cambian o los mensajes se muestran con otra estructura. Son detalles pequeños por separado, pero juntos pueden hacer que el formulario parezca ajeno a la página.

Un formulario bonito en HubSpot no siempre es un formulario bien integrado en WordPress. Por eso, con V4 conviene plantear los estilos como parte de una integración nueva, no como un apaño rápido sobre el CSS anterior.

Eventos y JavaScript: mismo objetivo, otro camino

Con JavaScript ocurre algo parecido. En formularios Legacy era habitual depender de callbacks como onFormReady, onFormSubmit u onFormSubmitted. Servían para preparar campos ocultos, enviar eventos a dataLayer, activar conversiones en Google Tag Manager o modificar algún detalle cuando el formulario terminaba de cargar.

En V4 también se puede trabajar con lógica personalizada, pero usando el sistema actual de eventos de HubSpot. La cuestión no es si se puede hacer, sino hacerlo de forma fiable y en el momento correcto.

Un ejemplo básico para detectar un envío correcto en V4 podría ser:

window.addEventListener('hs-form-event:on-submission:success', function(event) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
        event: 'hubspot_form_success',
        hubspotFormId: event.detail.formId,
        hubspotInstanceId: event.detail.instanceId
    });
});

Este código permite avisar a Google Tag Manager cuando HubSpot confirma que el formulario se ha enviado correctamente. La clave está en medir el envío real, no solo el clic en el botón. Medir clics como si fueran leads es una forma rápida de alegrarse en el dashboard y llevarse un disgusto después.

También puede afectar a los campos ocultos. Muchas webs guardan información como la URL de origen, UTMs, idioma, servicio de interés o página desde la que se envía el formulario. Si ese dato se rellenaba con JavaScript al cargar el formulario, hay que comprobar cómo hacerlo en V4 y validarlo con pruebas reales.

En resumen: con V4 se pueden conseguir muchos de los mismos objetivos que con Legacy, pero no copiando el mismo código tal cual. Hay que revisar estructura, selectores, eventos y datos. Es menos “pegar y listo” y más “integrar con cabeza”.

Si conviven Legacy y V4, separa CSS y JavaScript

En algunas webs no se puede pasar de formularios Legacy a formularios V4 de golpe. Puede haber landings antiguas, formularios con mucha lógica personalizada, campañas activas o páginas donde no conviene tocar demasiado porque cualquier fallo puede traducirse en pérdida de leads.

Y esto no tiene por qué ser un problema si se gestiona bien. Durante un tiempo pueden convivir ambos sistemas, pero conviene que cada uno tenga su propio espacio: CSS para Legacy, CSS para V4, JavaScript para Legacy y JavaScript para V4.

Mezclarlo todo en el mismo bloque de estilos o en el mismo archivo de scripts puede parecer rápido al principio, pero luego complica el mantenimiento. Un selector pensado para Legacy puede no tener sentido en V4. Un evento usado en V4 puede no existir en Legacy. Y una pequeña corrección para un formulario puede acabar afectando a otro sin que nadie lo vea venir.

Por eso, si la web mantiene formularios de ambos tipos, lo más limpio es separar la lógica desde el principio. No porque V4 sea más difícil de personalizar, sino porque se personaliza con otra estructura y otros eventos. Menos mezcla, menos sustos.

Esta separación también prepara la web para el futuro. Si en algún momento los formularios Legacy dejan de usarse por completo, será mucho más fácil retirar su CSS y su JavaScript sin deshacer una madeja de código mezclado. Menos arqueología frontend, más mantenimiento con calma.

En proyectos donde el formulario tiene mucho peso comercial, la migración debería hacerse por fases. Primero se identifica qué formularios existen, qué estilos y scripts dependen de cada uno, qué datos se envían y qué páginas generan más leads. Después se prueba la versión V4 en un entorno controlado y, solo cuando todo está validado, se sustituye en producción.

A veces, simplemente, no compensa cambiarlo todo en ese momento. Si una integración Legacy funciona bien, genera leads y el negocio no puede permitirse perder oportunidades comerciales, mantenerla temporalmente puede ser una decisión prudente. La clave está en no improvisar: documentar lo que hay, separar lo nuevo de lo heredado y planificar la migración con criterio.

Qué revisar antes de sustituir un formulario Legacy por uno V4

Antes de cambiar un formulario Legacy por uno V4, conviene hacer una revisión mínima de la integración actual. No basta con copiar el nuevo embed, pegarlo en WordPress y comprobar que aparece en pantalla. Eso solo confirma que el formulario carga, no que se integra igual de bien que antes.

Lo primero es identificar qué dependía del formulario anterior. Puede haber CSS específico para campos, labels, botones o mensajes de error. También puede haber JavaScript conectado a eventos como onFormReady u onFormSubmitted, campos ocultos que se rellenan automáticamente, envíos a dataLayer o pequeñas adaptaciones según la página donde se muestra el formulario.

Después hay que decidir qué se puede conservar, qué hay que adaptar y qué conviene rehacer para V4. Si el formulario Legacy estaba muy personalizado, lo normal es que la migración requiera trabajo real: nuevos selectores CSS, nuevos eventos, nuevas pruebas y una validación más cuidadosa del comportamiento.

No es porque V4 no permita hacerlo. Es porque hacer lo mismo en V4 puede requerir otra implementación.

También compensa priorizar. No todos los formularios tienen el mismo peso en el negocio. Una landing de campañas activas, una página de contacto que genera oportunidades comerciales o una solicitud de demo deberían revisarse con más cuidado que un formulario secundario con poco tráfico. Si algo falla ahí, no estamos hablando de un pequeño desajuste técnico, sino de posibles leads perdidos.

Una forma sencilla de empezar es hacerse estas preguntas antes de tocar nada:

La idea no es complicar la migración, sino evitar sorpresas. Si sabes qué hacía el formulario Legacy antes de sustituirlo, será mucho más fácil decidir si puedes pasar a V4 sin riesgo, si necesitas adaptar parte de la integración o si conviene mantener temporalmente el sistema actual hasta poder probarlo bien.

Cuándo usar V4, cuándo mantener Legacy y cuándo plantear una integración avanzada

No todos los formularios necesitan el mismo nivel de personalización ni tienen el mismo riesgo de negocio. Hay casos en los que un formulario V4 encaja perfectamente, otros donde mantener un Legacy durante un tiempo puede ser lo más sensato y otros donde conviene plantear una integración avanzada desde el principio.

Los formularios V4 tienen sentido cuando el equipo de marketing necesita más autonomía dentro de HubSpot, el diseño puede resolverse con una personalización específica para V4 y la lógica del formulario no depende de demasiados scripts heredados. Si el formulario es nuevo, no arrastra CSS antiguo ni eventos Legacy, suele ser una buena oportunidad para trabajar con una base más actual.

Mantener un formulario Legacy puede ser razonable cuando ya existe una integración estable, con mucho CSS o JavaScript personalizado, y el formulario está generando leads de forma fiable. Esto no significa dejarlo abandonado para siempre, sino evitar una migración precipitada en una parte crítica de la web. Si el negocio depende de esos formularios, cambiar sin pruebas no es valentía técnica: es jugar a la ruleta con la captación.

La integración avanzada entra en juego cuando necesitas más control: estilos muy ajustados al diseño de WordPress, tracking personalizado, campos ocultos con lógica propia, varios formularios en una misma página o requisitos concretos de analítica y atribución. En esos casos, V4 también puede ser una opción válida, pero hay que integrarlo con su propio enfoque, no como si fuera un Legacy con otro nombre.

En Bubuku solemos mirar este tipo de decisiones con una pregunta sencilla: ¿qué coste tendría que este formulario dejase de funcionar bien durante unas horas o unos días? Si la respuesta afecta a campañas, ventas o captación de clientes, entonces compensa dedicar tiempo a probar, separar estilos, revisar eventos y documentar la integración antes de tocar producción.

La mejor opción no es siempre la más moderna ni la más cómoda en HubSpot. Es la que permite que el formulario encaje con la web, mantenga la confianza del usuario y siga enviando los datos que el equipo necesita para trabajar cada lead con contexto.

Antes de darlo por bueno, comprueba algo más que el diseño

Al integrar un formulario de HubSpot en WordPress, la primera comprobación suele ser visual: que aparezca, que no rompa la página y que el botón tenga un aspecto decente. Es normal, porque es lo primero que se ve. Pero en formularios, esa revisión se queda corta.

Un formulario puede verse correcto y aun así estar fallando por debajo. Puede no estar aplicando bien los estilos en móvil, no lanzar los eventos JavaScript esperados, no rellenar campos ocultos, no enviar datos a analítica o no respetar el comportamiento que tenía la versión anterior.

Por eso, antes de publicar un cambio de Legacy a V4, conviene hacer una prueba completa: revisar el formulario en escritorio y móvil, enviar varios tests, comprobar que el lead llega a HubSpot con los datos correctos, validar los eventos en Google Tag Manager y confirmar que los mensajes de error y confirmación funcionan como deberían.

Aquí no se trata de desconfiar de V4. Se trata de recordar que hacer lo mismo con otra tecnología requiere volver a comprobarlo. Si antes una UTM se rellenaba con un callback Legacy y ahora se hace con eventos globales, hay que validar que el dato llega. Si antes el botón heredaba estilos del tema y ahora usa otra estructura, hay que revisarlo en la página real.

La clave está en tratar el formulario como lo que es: una pieza crítica de conversión. Aunque ocupe poco espacio en la página, puede ser el punto del que dependen nuevas solicitudes, oportunidades comerciales o campañas enteras. Si esa pieza falla, la web no solo pierde coherencia visual; puede perder negocio.

En resumen: los formularios Legacy y V4 de HubSpot se pueden personalizar e integrar en WordPress, pero no se trabajan igual. Merece la pena revisar HTML, CSS, JavaScript, eventos y datos antes de sustituir uno por otro. Mejor dedicar tiempo a validar la integración que descubrir tarde que el formulario estaba bonito, pero no estaba haciendo su trabajo.

Referencias

Para preparar y validar este artículo, conviene revisar la documentación oficial de HubSpot sobre formularios, estilos e integración en sitios externos:

• Global Form Events de HubSpot, donde se documenta el sistema actual de eventos para formularios, como hs-form-event:on-ready y hs-form-event:on-submission:success.
• Ajuste y estilo de formularios Legacy en sitios externos, donde HubSpot explica que los formularios Legacy pueden configurarse como raw HTML para renderizarse como HTML en la página externa en lugar de dentro de un iframe.
• Style and embed HubSpot forms on an external site, donde HubSpot indica que la opción de raw HTML no está disponible en el editor actualizado y que solo los formularios creados con el editor Legacy pueden usarla.
• Create and edit forms, documentación del editor actualizado de formularios, donde también se explica el funcionamiento del nuevo editor.
• Forms FAQ de HubSpot, donde HubSpot recuerda que sus formularios están construidos con JavaScript y que las personalizaciones avanzadas pueden requerir conocimientos técnicos o una integración mediante Forms API.

También puedes consultar este artículo relacionado de Bubuku sobre cómo integrar formularios de HubSpot en Webflow, donde se ve un caso práctico parecido desde otra plataforma visual. La idea de fondo es la misma: dar autonomía a marketing sin perder control sobre diseño, comportamiento y medición.

Si necesitas revisar cómo se están integrando tus formularios de HubSpot en WordPress, en Bubuku I Code podemos ayudarte a adaptar estilos, eventos y tracking para que el formulario no solo se vea bien, sino que siga haciendo su trabajo: captar leads con contexto y sin sustos.