Cómo enviar clientes potenciales de formularios de Webflow a Pipedrive como contactos con Webflow Cloud

A menudo, los leads de los formularios de Webflow llegan a Pipedrive de forma lenta. Alguien del equipo de ventas copia el nombre y el correo electrónico a mano, o bien una plataforma de automatización actúa como intermediaria, con tu token de Pipedrive almacenado en su pantalla de mapeo de campos.

En su lugar, puedes usar un gestor de rutas de Next.js desplegado en Webflow Cloud. Este recibe el webhook de envío del formulario de Webflow y, una vez validado un secreto compartido, crea la persona mediante la API v2 de Pipedrive en una sola llamada. Veamos cómo.

¿Qué necesitas para enviar leads de formularios a Pipedrive desde Webflow?

Necesitas estos seis elementos:

• Formulario de Webflow: Un formulario publicado cuyos nombres de campo estén configurados en el Designer, ya que esos nombres se convierten en las claves que el gestor mapea hacia Pipedrive.
• Entorno de Webflow Cloud: Un entorno en ese sitio; el plan Starter gratuito cubre un montaje sin dominio personalizado, mientras que un montaje con dominio personalizado requiere el plan Premium o superior.
• Token de API de Pipedrive: Un usuario de Pipedrive cuyo token de API personal puedas copiar, además de tu dominio de empresa, la yourcompany parte de yourcompany.pipedrive.com.
• Node.js y Next.js: Node.js 22 o posterior y Next.js 15 o superior con el App Router, según la documentación de Webflow sobre cómo integrar tu propia aplicación.
• npm: Webflow Cloud solo admite npm, por lo que los pasos de instalación de pnpm y yarn fallarán; todos los comandos de esta guía utilizan npm o npx.
• Secreto compartido: Una cadena aleatoria generada en tu equipo con openssl rand -hex 32, que el gestor espera como clave en la URL del webhook.

Con todo esto listo, el orden es: primero Pipedrive (para que puedas probar la llamada a la API de forma aislada), luego la aplicación y, finalmente, el webhook de Webflow que la alimenta.

5 pasos para enviar leads de formularios de Webflow a Pipedrive en Webflow Cloud

La construcción consiste en un gestor de rutas POST en Webflow Cloud que se sitúa entre el webhook de envío de formularios de Webflow y la API de Pipedrive, y la ruta de montaje determina la URL que el webhook debe llamar.

Una solicitud curl contra la ruta desplegada confirma la ruta de montaje y la llamada a Pipedrive antes de que se dispare cualquier formulario real.

1. Copia tu token de API de Pipedrive

En Pipedrive, abre el menú de tu perfil, luego Preferencias personales, después la pestaña API y copia tu token de API personal. Anota también tu dominio de empresa, ya que el gestor llama al endpoint de personas v2 de Pipedrive en ese dominio con el token en una cabecera x-api-token.

Pipedrive dejó de dar soporte a su endpoint v1 de creación de personas en agosto de 2026, por lo que los tutoriales antiguos que envían un campo email plano a /v1/persons ya no coinciden con la API actual.

El token nunca debe incluirse en el código personalizado de una página de Webflow: cualquier elemento en una página publicada puede ser leído por cualquiera que abra el código fuente, y este token otorga acceso mediante API a tu cuenta de Pipedrive.

Al finalizar este paso, tendrás dos cadenas: el token y el dominio de tu empresa, y aún no se habrá realizado ningún cambio en Pipedrive.

2. Prepara la estructura de la aplicación Next.js para Webflow Cloud

Crea un proyecto de Next.js desde cero con el App Router, usando npm, y deja la configuración predeterminada tal cual. La documentación de configuración de Webflow Cloud indica: "No necesitas añadir un adaptador, una ruta base ni un modo de salida", por lo que el proyecto inicial no requiere cambios.

No añadas export const runtime = 'edge' a ninguna ruta; el adaptador OpenNext de Cloudflare que utiliza Webflow Cloud para el despliegue no lo admite, por lo que la compilación fallará.

Ejecuta estos tres comandos para estructurar el proyecto y confirmar que funciona localmente:

npx create-next-app@15 webflow-pipedrive
cd webflow-pipedrive
npm run dev

Ahora tienes un proyecto que sirve la página predeterminada de Next.js en localhost, con un app directorio listo para app/api/pipedrive/route.ts. Ten en cuenta la ruta de montaje que planeas usar (esta compilación utiliza /leads), porque la URL pública de la ruta será esa ruta más /api/pipedrive una vez desplegada.

3. Escribe el controlador de ruta que crea el contacto en Pipedrive

Añade un controlador POST en app/api/pipedrive/route.ts que verifique un secreto compartido en la cadena de consulta. Una vez que la clave es validada, lee los campos del formulario desde el cuerpo del webhook y crea una persona en Pipedrive, enviando el correo electrónico y el teléfono como las matrices que espera la API v2.

Devuelve un 401 si la clave es incorrecta, un 500 si falta una variable de Pipedrive, un 400 si falta el campo de correo electrónico y un 502 si Pipedrive no está disponible o rechaza el registro; así, el código de estado te indica qué extremo falló. Un 200 con { ok: true } significa que la persona ya existe.

Código del controlador de ruta

Guarda esto como el archivo completo del controlador:

// app/api/pipedrive/route.ts
import { NextResponse } from 'next/server';

type Fields = Record<string, unknown>;

function extractFields(body: unknown): Fields {
  if (!body || typeof body !== 'object') return {};
  const b = body as { payload?: { data?: Fields }; data?: Fields };
  return b.payload?.data ?? b.data ?? (b as Fields);
}

function text(fields: Fields, key: string): string {
  const value = fields[key];
  if (typeof value === 'string') return value.trim();
  if (typeof value === 'number') return String(value);
  return '';
}

function safeEqual(a: string, b: string): boolean {
  if (a.length !== b.length) return false;
  let diff = 0;
  for (let i = 0; i < a.length; i++) {
    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }
  return diff === 0;
}

export async function POST(request: Request) {
  const key = new URL(request.url).searchParams.get('key') ?? '';
  const secret = process.env.WEBHOOK_SHARED_SECRET ?? '';
  if (!secret || !safeEqual(key, secret)) {
    return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
  }

  const domain = process.env.PIPEDRIVE_COMPANY_DOMAIN;
  const token = process.env.PIPEDRIVE_API_TOKEN;
  if (!domain || !token) {
    return NextResponse.json({ error: 'pipedrive not configured' }, { status: 500 });
  }

  const body = await request.json().catch(() => null);
  if (process.env.DEBUG_PAYLOAD === '1') {
    console.log('webflow payload', JSON.stringify(body));
  }

  const fields = extractFields(body);
  const email = text(fields, 'Email');
  const name = text(fields, 'Name') || email;
  const phone = text(fields, 'Phone');
  if (!email) {
    return NextResponse.json({ error: 'missing Email field' }, { status: 400 });
  }

  let response: Response;
  try {
    response = await fetch(`https://${domain}.pipedrive.com/api/v2/persons`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-token': token,
      },
      body: JSON.stringify({
        name,
        emails: [{ value: email, primary: true, label: 'work' }],
        ...(phone ? { phones: [{ value: phone, primary: true, label: 'work' }] } : {}),
      }),
      signal: AbortSignal.timeout(8000),
    });
  } catch (error) {
    console.error('pipedrive unreachable', error);
    return NextResponse.json({ error: 'pipedrive unreachable' }, { status: 502 });
  }

  if (!response.ok) {
    console.error('pipedrive error', response.status, await response.text());
    return NextResponse.json({ error: 'pipedrive rejected the contact' }, { status: 502 });
  }

  return NextResponse.json({ ok: true });
}

Las claves de campo Name, Email y Phone son los nombres establecidos en los campos del formulario en el Diseñador, y distinguen entre mayúsculas y minúsculas; si los nombres en tu formulario son diferentes, cambia las tres llamadas a text() para que coincidan.

La documentación de webhooks de Webflow muestra los campos del formulario bajo payload.data, organizados por el nombre de cada campo, con números de teléfono que a veces llegan como números en lugar de cadenas, razón por la cual text() acepta ambos.

La DEBUG_PAYLOAD puerta te permite confirmar las claves exactas de tu propio formulario. La comparación del secreto verifica cada carácter en lugar de detenerse en la primera discrepancia, y está escrita manualmente porque crypto.subtle.timingSafeEqual existe en el entorno de ejecución de Workers desplegado, pero no bajo next dev local.

Tras guardar el archivo, ya tienes un controlador completo que compila con npm run dev y devuelve el cuerpo JSON 401 para una solicitud POST a la ruta local sin una clave.

4. Añade las variables de entorno y despliega

Desde el panel de Webflow Cloud del sitio, crea un proyecto vinculado al repositorio que contiene la aplicación. Dentro de ese proyecto, crea un entorno y establece su ruta de montaje en /leads. Añade las cuatro variables siguientes en la configuración de ese entorno y luego despliega.

Marca el token y el secreto como secretos. La documentación de variables de entorno de Webflow establece que "tanto las variables de entorno secretas como las no secretas están disponibles para el proceso de compilación de tu aplicación y para la aplicación desplegada en tiempo de ejecución", y los secretos se ocultan en los registros de compilación, por lo que un token mal escrito no puede leerse desde el registro; en su lugar, verifícalo mediante el comportamiento.

Funciones de las variables de entorno

Cada variable tiene una función específica en el controlador:

• WEBHOOK_SHARED_SECRET: La cadena hexadecimal aleatoria de openssl rand -hex 32; utiliza el mismo valor en el entorno y en la URL del webhook; para rotarla, deberás cambiar ambos lugares.
• PIPEDRIVE_API_TOKEN: El token de API de Pipedrive copiado desde la pestaña de API en las preferencias personales de Pipedrive, almacenado como un secreto para que se oculte en los registros de compilación y nunca se suba al repositorio.
• PIPEDRIVE_COMPANY_DOMAIN: El dominio de tu empresa en Pipedrive sin .pipedrive.com, por ejemplo acme.
• DEBUG_PAYLOAD: Configúralo como 1 para el primer despliegue con el fin de registrar el cuerpo del webhook sin procesar, luego elimínalo para que los datos de los clientes potenciales dejen de aparecer en los registros.

Una vez finalizado el despliegue, el controlador estará activo en /leads/api/pipedrive con las cuatro variables disponibles durante la compilación y la ejecución.

Prueba del controlador

Introduce tu secreto y tu dominio, y luego envía esta solicitud a la ruta desplegada:

curl -i -X POST "https://www.example.com/leads/api/pipedrive?key=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"Name":"Test Lead","Email":"test@example.com","Phone":"+1 555 0100"}'

El host www.example.com representa un dominio personalizado, lo cual requiere Premium; si no tienes un dominio personalizado, sustitúyelo por el dominio de tu entorno y mantén /leads/api/pipedrive.

Una respuesta 200 con {"ok":true} y una nueva persona llamada Test Lead en Pipedrive significa que ambas partes de la integración funcionan. Un error 500 indica que falta una de las variables de Pipedrive, un 502 apunta a la URL del endpoint, al nombre del encabezado o al token, y un 404 señala la ruta de montaje en la URL.

5. Apunta el webhook del formulario de Webflow a la ruta

Apunta un webhook de envío de formulario a https://www.example.com/leads/api/pipedrive?key=YOUR_SECRET con tu propio dominio y secreto para enviar cada envío de formulario al controlador. En la configuración de webhooks del sitio, añade un webhook con el envío de formulario como activador y verifica que la URL mantenga la ruta de montaje antes de /api/pipedrive.

Webflow solo firma los webhooks creados a través de su API, y un webhook añadido en la configuración del sitio llega sin firmar, por lo que la clave de consulta es la única verificación del emisor en este caso. Trátala como una contraseña, ya que la URL lleva el secreto en texto plano y las cadenas de consulta pueden terminar en los registros de solicitudes durante el proceso.

En los sitios de clientes, suelo rotar el secreto cuando un editor con acceso a la configuración se marcha, lo cual implica cambiar dos campos.

Luego, abre el sitio publicado, rellena el formulario con un correo electrónico que parezca real y envíalo. El mismo nombre y correo electrónico deberían aparecer como una persona en Pipedrive. Con DEBUG_PAYLOAD configurado, la línea de registro webflow payload muestra el paquete que recibió el controlador; si difiere de la estructura anidada payload.data que espera el controlador, ajusta extractFields para que coincida.

¿Qué causa que la sincronización de clientes potenciales de Webflow a Pipedrive falle?

La mayoría de los fallos se deben a una de estas cuatro causas, y el código de estado de la prueba curl indica cuál es.

La compilación en Webflow Cloud falla en una ruta que se compiló localmente

Causa: La ruta contiene export const runtime = 'edge', lo cual no es compatible con el adaptador de Cloudflare OpenNext que utiliza Webflow Cloud. La palabra "edge" significa dos cosas distintas en la misma página de documentación.

Webflow Cloud se ejecuta en Cloudflare Workers, una plataforma edge, y la página de "bring-your-own-app" describe ese despliegue como el uso del entorno de ejecución Edge. La misma página te indica que añadidas la directiva de entorno de ejecución edge de Next.js a las rutas de la API, y seguirla produce una ruta que no se puede compilar.

Solución: Elimina la línea export const runtime = 'edge' de cada archivo de ruta y página, y vuelve a desplegar. Si más adelante mueves la verificación del secreto al middleware, mantén el archivo llamado middleware.ts.

La documentación sobre personalización de frameworks de Webflow indica: "El middleware de tiempo de ejecución de Node.js no es compatible. Solo el middleware de tiempo de ejecución Edge funciona en el entorno de Workers", y el proxy.ts renombrado de Next 16 se ejecuta en el entorno de Node sin posibilidad de optar por Edge.

Los envíos de formularios nunca llegan al controlador y la URL activa devuelve un error 404

Causa: A la URL del webhook le falta la ruta de montaje. Webflow Cloud inyecta basePath durante la compilación, por lo que una ruta escrita en app/api/pipedrive/route.ts es pública en la ruta de montaje más /api/pipedrive, nunca en la raíz del sitio. Una URL copiada de una sesión local de next dev, donde la ruta respondía en /api/pipedrive, devuelve un 404 en el dominio activo.

El mismo desajuste ocurre a la inversa si añades un formulario en el lado del navegador dentro de la propia aplicación, ya que la documentación de Webflow es clara: "Las llamadas fetch del lado del cliente deben incluir manualmente la ruta base".

Solución: Edita la URL del webhook para incluir el segmento de montaje (/leads/api/pipedrive en esta compilación) y vuelve a enviar el formulario. Para cualquier fetch del lado del cliente dentro de la aplicación, establece NEXT_PUBLIC_BASE_PATH como la ruta de montaje en una variable de entorno y anteponla a la solicitud en lugar de leer basePath desde next.config.

Una forma rápida de confirmar la ruta correcta antes de tocar el webhook es realizar una prueba curl contra la ruta desplegada: un error 401 demuestra que la ruta es accesible y que solo la clave es incorrecta, mientras que un 404 demuestra que la ruta en sí no es la adecuada.

La ruta desplegada devuelve un error 500 o 502, pero la misma solicitud funciona desde tu ordenador

Causa: A la aplicación desplegada le falta un valor de Pipedrive o este es incorrecto. Si PIPEDRIVE_API_TOKEN o PIPEDRIVE_COMPANY_DOMAIN no están presentes en el entorno desde el que se despliega la aplicación, el controlador devuelve un 500 con el mensaje "pipedrive not configured" y nunca llega a llamar a Pipedrive.

Un valor que solo existe en .env.local está ausente en el entorno desplegado. Un token o dominio incorrecto llega a Pipedrive y falla allí; quien realiza la llamada ve un 502 y el estado de Pipedrive aparece en la línea console.error.

Solución: Abre el entorno desde el que se despliega la aplicación activa, añade ambas variables allí y vuelve a desplegar. Para comprobar la configuración sin mostrar el token, registra token.length y domain una vez detrás de la puerta DEBUG_PAYLOAD; la longitud mostrará si el secreto está vacío y el dominio debería coincidir con tu dirección de Pipedrive. Una vez que el error desaparezca, elimina la línea de registro adicional.

La ruta desplegada devuelve un error 401 aunque la clave parece correcta

Causa: El valor key en la URL del webhook difiere de WEBHOOK_SHARED_SECRET en el entorno, por lo que la comparación falla antes de que se llame a Pipedrive. Por lo general, el secreto se rotó en un lugar pero no en el otro, o se incluyeron espacios en blanco accidentales al copiar y pegar.

Una clave que contiene caracteres que requieren codificación URL provoca el mismo desajuste, algo que la salida hexadecimal de openssl rand -hex 32 evita.

Solución: Vuelve a copiar el mismo secreto tanto en la variable WEBHOOK_SHARED_SECRET como en la URL del webhook, vuelve a desplegar y ejecuta de nuevo la prueba curl contra la ruta desplegada. Un 200 confirma que ambos valores coinciden ahora; un 401 significa que siguen siendo diferentes.

Qué puedes construir a continuación con Pipedrive y Webflow

Puedes ampliar este controlador para buscar a una persona existente antes de crearla, o para añadir un cliente potencial o trato vinculado a la nueva persona para que llegue al embudo de ventas. El mismo patrón de webhook también envía clientes potenciales a HubSpot sin necesidad de un servicio intermedio.

Para una personalización más profunda más allá de lo que gestiona de forma nativa el webhook del formulario, la documentación para desarrolladores de Webflow cubre el evento de envío de formularios y el resto de la API de datos.