Cómo integrar n8n con HubSpot paso a paso (2026)
Guía técnica para integrar n8n con HubSpot en un equipo B2B: cómo crear el Private App con los scopes correctos para contactos, empresas y Leads, cuándo elegir un webhook frente a un sondeo programado, cómo mapear propiedades estándar y personalizadas sin romper el pipeline, cómo aplicar idempotencia para no duplicar contactos, cómo separar el portal de pruebas del de producción, y cómo diagnosticar los errores más frecuentes, 401, scope ausente, límite de peticiones, antes de que bloqueen un flujo en producción en España y la UE.
La mayoría de las guías sobre conectar n8n con un CRM tratan a HubSpot como si fuera un formulario genérico con campos de texto. No lo es: tiene propiedades con nombre interno distinto al que ves en pantalla, pipelines con identificadores propios por etapa, un modelo de asociaciones entre contactos, empresas y Leads, y un sistema de permisos por Private App que decide qué puede tocar cada token. Integrar n8n con HubSpot bien montado no consiste en arrastrar un nodo y rellenar cuatro campos: consiste en decidir de antemano qué dispara el flujo, qué scopes necesita el token, cómo evitas crear el mismo contacto dos veces y qué pasa el día que HubSpot devuelve un error 401 en mitad de la jornada comercial.
El vídeo repasa cómo montar la integración completa entre n8n y HubSpot: la creación del Private App y los scopes que necesita cada objeto, la diferencia práctica entre disparar el flujo con un webhook o con un sondeo programado, el mapeo de propiedades estándar y personalizadas de contacto y Lead, cómo evitar contactos duplicados con una operación de upsert, y el patrón completo de contacto creado, enriquecido y convertido en Lead con aviso al comercial.
Transcripción del vídeo
Conectar n8n con HubSpot permite automatizar tareas comerciales que, de otro modo, exigen copiar datos a mano o depender de integraciones rígidas. Incluso con una cuenta gratuita o de nivel básico, podéis crear flujos que den de alta contactos, actualicen propiedades o reaccionen a eventos del CRM desde el editor visual de n8n.
En n8n, abrid la sección de credenciales desde el menú superior y elegid Create Credential. Buscad HubSpot y seleccionad App Token, la opción adecuada para la mayoría de integraciones internas.
Por qué integrar n8n con HubSpot bien montado ahorra semanas de arreglos
Un flujo de n8n conectado a HubSpot que funciona en la demo de la primera semana y falla en la tercera casi siempre comparte el mismo origen: se diseñó pensando en el camino feliz, sin decidir de antemano qué pasa con un token revocado, un contacto que ya existía o una etapa de pipeline que cambió de nombre.
El coste real no es la integración, es el primer contacto duplicado que llega a ventas
HubSpot cambia con más frecuencia de lo que asume un flujo estático
Este artículo no repite la guía genérica de conectar un formulario a un CRM
Qué es (y qué no es) integrar n8n con HubSpot
Antes de tocar un solo nodo conviene fijar qué resuelve esta integración y qué problemas quedan fuera de su alcance, porque confundirlos es la causa más común de expectativas mal calibradas.
No es sustituir el CRM, es automatizar lo que pasa alrededor de él
n8n no reemplaza a HubSpot como fuente de verdad de tus contactos, empresas y Leads: actúa como la capa que conecta HubSpot con todo lo que vive fuera de él, tu web, tu ERP, tu herramienta de enriquecimiento, tu canal de Slack, sin copiar datos a mano entre sistemas. HubSpot sigue siendo el registro comercial de referencia; n8n es la tubería que lo mantiene actualizado.
No es una integración de una sola dirección por defecto
No es una integración que se configura una vez y se olvida
Los pipelines cambian de etapas, las propiedades personalizadas se añaden o se retiran, y los tokens de Private App se rotan por seguridad. Tratar la integración como un proyecto cerrado en lugar de como un componente que necesita revisión periódica es la razón por la que muchos flujos que funcionaban bien durante meses empiezan a fallar sin que nadie haya tocado el flujo de n8n directamente.
El Private App de HubSpot. Scopes imprescindibles para contactos, empresas y Leads
Desde que HubSpot retiró las API Keys clásicas, cualquier conexión programática, incluida la de n8n, pasa por un Private App: una integración interna del propio portal que genera un token con permisos (scopes) definidos objeto a objeto.
Crear el Private App desde Configuración, Integraciones
Los scopes mínimos por objeto, sin conceder de más
Leads ).
El token empieza por pat- y se guarda una sola vez
HubSpot muestra el token del Private App una única vez tras crearlo o regenerarlo, con el prefijo característico pat-. Guárdalo directamente en una credencial de n8n en lugar de pegarlo en un documento de texto compartido, y documenta en algún registro interno cuándo se generó y quién es responsable de regenerarlo si se revoca por error o por rotación de seguridad.
Disparadores del flujo. Webhook nativo, acción de webhook en un Workflow o sondeo
La decisión de qué dispara el flujo en n8n condiciona la latencia, la complejidad de mantenimiento y hasta la superficie de seguridad expuesta, así que merece más reflexión que elegir lo primero que aparece en la lista de nodos.
La acción de webhook dentro de un Workflow de HubSpot es la opción más accesible
La suscripción nativa de webhooks de la API cubre casos que un Workflow no alcanza
Cuando necesitas reaccionar a eventos que no encajan bien en la lógica de un Workflow, por ejemplo, cualquier cambio en una propiedad concreta de cualquier contacto, sin pasar por una inscripción manual, la suscripción de webhooks a nivel de API es la opción más flexible.
El sondeo programado sigue siendo razonable cuando no hace falta reaccionar en segundos
Un nodo de tipo Schedule que ejecuta cada cierto intervalo una búsqueda de contactos o Leads modificados desde la última ejecución, filtrando por la propiedad de fecha de última modificación, evita exponer cualquier endpoint público y es más fácil de depurar que un webhook, a costa de una latencia igual al intervalo elegido. La clave para que el sondeo no pierda eventos es guardar de forma fiable la marca de tiempo de la última ejecución correcta, no solo confiar en que la próxima vez ya cogerá lo que falte.
Mapear propiedades de contacto y de Lead, incluidas las personalizadas
El error de mapeo más frecuente no es escribir en el campo equivocado, es escribir en el campo correcto con el valor equivocado porque HubSpot distingue entre lo que ves en pantalla y lo que espera recibir por API.
El nombre interno de una propiedad casi nunca coincide con su etiqueta visible
Los campos de tipo desplegable exigen el valor interno de la opción, no la etiqueta
Una propiedad de tipo enumerado, como el origen del lead o el tamaño de empresa, guarda internamente un valor distinto al texto que se muestra en el desplegable, y enviar por API la etiqueta visible en lugar del valor interno de esa opción produce un error de validación o, peor, un valor vacío que nadie detecta hasta que alguien revisa el informe de segmentación semanas después.
El pipeline y la etapa del Lead se identifican por ID, no por nombre
Al crear o mover un Lead, HubSpot espera el identificador interno del pipeline y de la etapa, no el texto que aparece en el tablero visual.
Evitar contactos duplicados. La idempotencia como norma, no como parche
El upsert por email resuelve el caso de contactos en una sola llamada
los Leads necesitan una clave de idempotencia propia porque no tienen email
Los reintentos de webhook son la fuente de duplicados más difícil de detectar
Portal de pruebas y portal de producción. Cómo separarlos sin dolor
Probar un flujo nuevo directamente contra el portal de producción de HubSpot es la manera más rápida de ensuciar la base de datos comercial real con contactos de prueba, Leads ficticios y notificaciones que llegan a comerciales reales por error.
Un sandbox estándar evita tocar datos reales durante el desarrollo
Los planes de HubSpot que incluyen un entorno sandbox estándar permiten crear una copia funcional del portal, con su propio Private App y sus propios pipelines, donde puedes forzar errores, probar cargas masivas o cambiar el mapeo de propiedades sin riesgo sobre el portal que usa el equipo comercial cada día. Validar el flujo entero en ese entorno antes de moverlo a producción reduce de forma drástica los incidentes que llegan a afectar a datos reales.
Sin sandbox, la separación mínima es un Private App y una credencial distintos
El flujo de n8n debe saber en qué entorno se ejecuta, no adivinarlo
Usar variables de entorno o credenciales con nombres inequívocos, HubSpot Test frente a HubSpot Producción, y comprobar de forma explícita cuál está activa antes de ejecutar cualquier acción de escritura evita el error clásico de mover un flujo de pruebas a producción sin cambiar la credencial, que es exactamente el tipo de fallo que solo se detecta cuando ya ha escrito varios registros donde no debía.
El patrón práctico. Contacto creado, enriquecido y convertido en Lead
Este es el flujo que resume casi todo lo anterior en un caso de uso concreto y reproducible: un contacto nuevo entra en HubSpot y, sin intervención manual, termina convertido en una oportunidad visible para el comercial correcto.
Paso uno. Detectar el contacto creado con el disparador adecuado
El flujo arranca con una acción de webhook en un Workflow de HubSpot inscrito en contacto creado, o con la suscripción nativa de webhooks al mismo evento si necesitas capturarlo sin pasar por un Workflow visual.
Paso dos. Enriquecer el contacto antes de decidir nada sobre el Lead
Con el identificador recibido, el flujo consulta el contacto completo en HubSpot y, si el dominio de correo lo permite, cruza esa información con la empresa asociada, creándola si no existe, con su propio upsert por dominio, para que el Lead nazca ya vinculado a la empresa correcta, no como un registro huérfano que alguien deberá enlazar a mano más tarde.
Paso tres. Crear o actualizar el Lead y avisar al comercial correcto
Errores frecuentes de conexión. 401, scopes que faltan y límite de peticiones
Casi todos los fallos de conexión entre n8n y HubSpot se agrupan en tres códigos de estado, y diagnosticarlos rápido depende de saber qué pregunta hacerse ante cada uno.
401. El token dejó de ser válido, no está mal escrito
403. El token es válido, pero le falta el scope de ese objeto concreto
429. El flujo está pidiendo más de lo que el plan permite por segundo
Comparativa. Qué disparador usar para conectar n8n con HubSpot según el caso
Usa esta tabla como referencia rápida antes de decidir con qué disparador arranca cada flujo nuevo entre n8n y HubSpot.
| Disparador | Latencia | Complejidad | Cuándo usarlo |
|---|---|---|---|
| Acción de webhook en un Workflow de HubSpot | Baja (casi inmediata) | Baja-media (sin API de suscripciones) | Cuando ya usas Workflows de HubSpot para segmentar y solo falta avisar a n8n en un punto concreto |
| Suscripción nativa de webhooks (API) | Baja (casi tiempo real) | Media-alta (endpoint público y validación de firma) | Cuando necesitas reaccionar a cualquier cambio de un objeto sin depender de un Workflow visual |
| Sondeo (polling) programado | Media (según el intervalo del cron) | Baja (nodo Schedule + búsqueda por fecha) | Cuando no hace falta reacción inmediata y quieres evitar exponer un endpoint público |
| Envío de formulario de HubSpot | Baja para ese evento concreto | Media (requiere el formulario y su suscripción) | Cuando el origen del contacto es siempre un formulario de marketing, no cualquier alta |
Errores frecuentes al integrar n8n con HubSpot
Estos fallos aparecen sobre todo en equipos que copiaron un tutorial genérico de webhooks sin adaptarlo al modelo de datos concreto de HubSpot.
- Conceder todos los scopes por si acaso: ampliar la superficie de riesgo del token sin ninguna ventaja funcional real.
- Mapear por la etiqueta visible en lugar del nombre interno de la propiedad: provocar errores de validación silenciosos que nadie detecta hasta el informe.
- Encadenar buscar y crear en dos pasos separados: abrir una ventana de condición de carrera que produce contactos duplicados.
- No dar a los Leads una clave de idempotencia propia: asumir que el email sirve también para identificar de forma única una oportunidad.
- Probar el flujo nuevo directamente en el portal de producción: ensuciar la base de datos comercial real con registros de prueba.
- Tratar cada reintento de webhook como un evento nuevo: duplicar registros exactamente en los picos de carga, que es cuando menos conviene.
- Procesar lotes grandes sin pausa ni reintento con espera: agotar el límite de peticiones por segundo del plan a mitad de la sincronización.
- No documentar quién puede regenerar el token del Private App: perder horas localizando a la persona responsable cuando el flujo empieza a devolver 401.
Revisa esta lista cada vez que muevas un flujo de pruebas a producción, no solo la primera vez que conectas n8n con HubSpot.
¿Cómo encaja este flujo con el EU AI Act y el RGPD?
El Reglamento (UE) 2024/1689 (EU AI Act) ya está en vigor. Si tu equipo usa automatizaciones con nodos de IA en n8n (Gemini, OpenAI, Claude u otros), la empresa actúa como desplegadora (deployer): no hace falta haber creado el modelo. Desde el 2 de febrero de 2025 el Artículo 4 exige un nivel suficiente de alfabetización en IA para quien opera estos sistemas. En España, la supervisión se articula con la AESIA (IA) y la AEPD (RGPD).
El RGPD sigue aplicando a nombres, correos y cargos de Leads B2B: base jurídica, minimización y, si hay perfiles automatizados a escala, evaluación de impacto.
Detalle de transparencia Logixb2b: Uso responsable de IA y Transparencia .
Evalúa tus horas y riesgos con el Auditor de Eficiencia Operativa B2B.
Checklist de scopes y hoja de mapeo de propiedades
Copia esta checklist antes de dar por cerrada cualquier integración nueva entre n8n y HubSpot, y vuelve a ella cada vez que el flujo cambie de objeto o de pipeline.
CHECKLIST DE SCOPES Y MAPEO, n8n + HUBSPOT (ES/UE)
Portal: ___________ Private App: ___________ Fecha: ___________
1. SCOPES DEL PRIVATE APP (mínimos por objeto)
[ ] crm.objects.contacts.read / .write
[ ] crm.objects.companies.read / .write
[ ] crm.objects.Leads.read / .write
[ ] crm.schemas.contacts.read (si usas propiedades personalizadas)
[ ] crm.objects.owners.read (si asignas propietario del Lead)
[ ] webhooks (solo si usas la suscripción nativa de la API, no la acción de Workflow)
2. TOKEN Y CREDENCIAL EN N8N
[ ] Token del Private App generado (empieza por pat-)
[ ] Credencial HubSpot creada en n8n con ese token: sí / no
[ ] Fecha de última rotación del token: ___________
[ ] Responsable de regenerar el token si se revoca: ___________
3. HOJA DE MAPEO, CONTACTO
Origen (tu sistema) Propiedad interna HubSpot Tipo
_________________________ email string (clave de upsert)
_________________________ firstname string
_________________________ lastname string
_________________________ company string
_________________________ phone string
_________________________ ___________________________ ___________ (personalizada)
4. HOJA DE MAPEO, LEAD
Origen Propiedad interna Tipo / formato
_________________________ dealname string
_________________________ pipeline ID interno (no la etiqueta visible)
_________________________ dealstage ID interno (no la etiqueta visible)
_________________________ amount number
_________________________ external_id string (clave de idempotencia)
5. IDEMPOTENCIA
[ ] Contactos: upsert por email en lote, no búsqueda + creación separadas
[ ] Leads: propiedad external_id comprobada antes de crear
[ ] Reintentos de webhook probados sin generar duplicados: sí / no
6. ENTORNOS
[ ] Portal de pruebas (sandbox o Private App separado): sí / no
[ ] Credenciales de n8n diferenciadas por entorno (test / producción): sí / no
7. LÍMITES Y ERRORES CONOCIDOS
[ ] Límite de peticiones por segundo del plan verificado: ___________
[ ] Reintento con espera creciente activado ante error 429: sí / no
[ ] Última revisión de logs de error 401/403: ___________
Revisado por: RevOps ___________ Admin. HubSpot ___________ Fecha: ___________Preguntas frecuentes
¿Qué scopes necesita el Private App de HubSpot para conectarlo con n8n?
write.
¿Es mejor usar un webhook o el sondeo (polling) para conectar HubSpot con n8n?
Depende de cuánto te cuesta esperar.