Cómo enviar correos electrónicos de comercio electrónico segmentados con Klaviyo y Webflow Cloud

Un flujo de Klaviyo es tan eficaz como los datos que lo alimentan, y en una tienda Webflow esos datos provienen de dos fuentes distintas. Las visitas a productos ocurren en el navegador del comprador, donde cualquiera puede ver y alterar lo que se envía, mientras que los pedidos se registran en los servidores de Webflow, donde son totalmente fiables. Un flujo que reacciona a ambos necesita que cada evento se capture donde realmente sucede.

El marco de integración personalizado de Klaviyo resuelve esto dividiendo las responsabilidades. Al usar JavaScript del lado del cliente para rastrear las visitas a productos y una ruta de servidor segura de Webflow Cloud para validar los webhooks de pedidos, puedes activar flujos automatizados de forma segura sin riesgo de solicitudes falsificadas o datos de clientes comprometidos.

En esta guía, veremos cómo configurar el seguimiento de navegación, gestionar webhooks de pedidos firmados y crear flujos automatizados para el abandono de navegación y la interacción tras la compra.

¿Qué necesitas para enviar correos electrónicos segmentados de Klaviyo en Webflow?

Necesitas cinco cosas:

• Un sitio de Ecommerce en Webflow: Productos publicados y un plan de Ecommerce, que genera webhooks de pedidos. Pegar el script de Klaviyo en el encabezado del sitio requiere un plan de sitio o de espacio de trabajo de pago, y cualquier plan de Ecommerce es válido.
• Claves pública y privada de Klaviyo: La clave pública de seis caracteres para el script del sitio y una clave privada con el events:write ámbito necesario para la ruta del servidor.
• Token del sitio de Webflow: Un token de API del sitio con el sites:write ámbito necesario, utilizado una vez para crear el webhook de pedidos.
• Proyecto Next.js: Next.js 15 o superior en Node.js 22 o posterior, instalado con npm, el único gestor de paquetes que admite Webflow Cloud.
• Repositorio Git: Un repositorio para la aplicación, propiedad de quien sea el dueño del sitio a largo plazo, para que la canalización de despliegue sobreviva al cambio de contratista.

Con todo esto listo, la parte del navegador requiere tres pasos y no necesita código fuera del Diseñador, mientras que la parte del servidor requiere cuatro.

7 pasos para enviar correos electrónicos segmentados de Klaviyo en Webflow Cloud

Los pasos 1 a 3 cubren la parte del navegador y los pasos 4 a 7 la del servidor, finalizando con los flujos que utilizan ambos. Sigue este orden, ya que los flujos del paso 7 necesitan que ambos tipos de eventos existan antes de que puedas seleccionarlos.

1. Añade el script de Klaviyo al encabezado del sitio

El script de Klaviyo permite que el navegador sea reconocido por la plataforma y registra su actividad. En Klaviyo, abre Ajustes, luego la pestaña de claves API y copia la clave pública de seis caracteres. Está diseñada para ser pública, por lo que es segura en el código de la página.

En Webflow, abre Ajustes del sitio > Código personalizado y pega esto en el código del encabezado, reemplazando PUBLIC_API_KEY con tu clave:

<script async type="text/javascript" src="https://static.klaviyo.com/onsite/js/PUBLIC_API_KEY/klaviyo.js"></script>
<script>
!function(){if(!window.klaviyo){window._klOnsite=window._klOnsite||[];try{window.klaviyo=new Proxy({},{get:function(n,i){return"push"===i?function(){var n;(n=window._klOnsite).push.apply(n,arguments)}:function(){for(var n=arguments.length,o=new Array(n),w=0;w<n;w++)o[w]=arguments[w];var t="function"==typeof o[o.length-1]?o.pop():void 0,e=new Promise((function(n){window._klOnsite.push([i].concat(o,[function(i){t&&t(i),n(i)}]))}));return e}}})}catch(n){window.klaviyo=window.klaviyo||[],window.klaviyo.push=function(){var n;(n=window._klOnsite).push.apply(n,arguments)}}}}();
</script>

La primera etiqueta carga el script. La segunda es el cargador propio de Klaviyo para el objeto klaviyo , copiado sin cambios de la documentación de Klaviyo.

Crea un sustituto que pone en cola cada llamada klaviyo.track y klaviyo.identify realizada antes de que el script termine de cargarse, para que una página de producto pueda registrar una visita sin esperas. Publica el sitio y ábrelo en un navegador: la pestaña Red debería mostrar klaviyo.js cargándose desde static.klaviyo.com.

2. Rastreo de productos vistos en la plantilla de producto

Un flujo de abandono de navegación se activa con una métrica llamada Producto Visto, y Klaviyo documenta las propiedades que espera. La plantilla de producto es el lugar donde pertenece esa llamada, ya que cada página de producto se genera a partir de ella.

Abre la página de la plantilla de Productos en el Diseñador. Selecciona el encabezado del nombre del producto y, en la configuración de su elemento, añade un atributo personalizado llamado data-product-name. Haz lo mismo en la imagen principal del producto con data-kl-namedata-product-imagedata-kl-image. Estos atributos son marcadores estáticos, por lo que el script encuentra los valores renderizados sin necesidad de vinculación CMS dentro del código.

Luego, abre la configuración de la página de la plantilla y añade esto antes de la etiqueta de cierre body:

<script>
(function () {
  var nameEl = document.querySelector('[data-kl-name]');
  if (!nameEl) return;
  var imageEl = document.querySelector('[data-kl-image]');
  var slug = window.location.pathname.split('/').filter(Boolean).pop() || '';
  klaviyo.track('Viewed Product', {
    ProductName: nameEl.textContent.trim(),
    ProductID: slug,
    URL: window.location.origin + window.location.pathname,
    ImageURL: imageEl ? imageEl.currentSrc || imageEl.src : undefined
  });
})();
</script>

ProductIDdata-product-slug es el slug del producto a propósito. La ruta de pedido en el paso 6 envía el mismo slug en cada evento de Producto Pedido, para que Klaviyo pueda hacer coincidir un producto visto con uno comprado. Todavía no se registra nada para un visitante primerizo, lo cual se soluciona en el paso 3.

3. Identificar a los compradores para que Klaviyo pueda enviarles correos electrónicos

En palabras de Klaviyo, su seguimiento en el sitio "solo rastrea la actividad de navegación de 'navegadores conocidos'", lo que significa navegadores que ya ha identificado o a los que ha asignado una cookie. Las vistas de productos de un visitante anónimo no van a ninguna parte, por lo que el flujo de abandono de navegación depende de que los compradores se vuelvan conocidos primero.

La ruta más sencilla es un formulario de registro creado en el generador de formularios de Klaviyo. Sus formularios tipo ventana emergente se publican a través del script que instalaste en el paso 1 e identifican al navegador cuando alguien envía sus datos. Klaviyo identifica a un comprador que hace clic en un enlace de un correo electrónico de Klaviyo de la misma manera.

Si prefieres mantener un formulario de boletín informativo creado en Webflow, dale al elemento de formulario un atributo personalizado llamado data-klaviyo-formdata-kl-signup y añade esto a esa página:

<script>
(function () {
  var form = document.querySelector('[data-kl-signup]');
  if (!form) return;
  form.addEventListener('submit', function () {
    var input = form.querySelector('input[type="email"]');
    if (input && input.value) klaviyo.identify({ email: input.value.trim() });
  });
})();
</script>

Identificar a un navegador no lo suscribe al marketing. El consentimiento es una decisión separada que tomas en el flujo del paso 7. Para confirmar la identificación, envía el formulario con tu propia dirección, luego abre una página de producto y busca un evento de Producto Visto en tu perfil de Klaviyo.

4. Preparar la aplicación Webflow Cloud y configurar sus variables

La mitad del servidor es una aplicación Next.js con un manejador de rutas, montada en tu sitio por Webflow Cloud. Prepárala con npm:

npx create-next-app@15 klaviyo-orders --typescript --app --no-src-dir --import-alias "@/*" --use-npm
cd klaviyo-orders

Deja adapter sin cambios; la página de "trae tu propia aplicación" de Webflow lo muestra como "Sin adaptador, sin ruta base, sin wrangler.json". No añadas next.configedgeexport const runtime = 'edge' a ninguna ruta.

Webflow Cloud ejecuta la aplicación en Cloudflare Workers, una plataforma perimetral, pero el tiempo de ejecución nodeedge de Next.js es independiente, y el adaptador OpenNext Cloudflare que construye Webflow Cloud no lo admite.

En Klaviyo, crea una clave API privada nombrada para esta aplicación solo con el alcance trackevents:write, y anota la fecha de revisión de la API actual que se muestra en la referencia de la API de Klaviyo.

Crea un proyecto de Webflow Cloud y un entorno montado en una ruta como /api/klaviyo, y añade tres variables, marcando la primera y la última como secretas:

• KLAVIYO_PRIVATE_KEY: La clave privada, almacenada como secreta para que Webflow Cloud la oculte de los registros de compilación.
• KLAVIYO_REVISION: La fecha de revisión. Klaviyo retira una revisión dos años después de su lanzamiento, así que actualízala según el calendario.
• WEBFLOW_WEBHOOK_SECRET: Déjala vacía por ahora. El paso 7 crea el webhook y te da su valor.

Para ejecuciones locales, refléjalas en un archivo .env.local que se mantenga fuera de git, luego ejecuta .env.localnpm run dev y confirma que la página predeterminada se carga en npm run devlocalhost:3000localhost:3000.

5. Escribe el cliente de Klaviyo del lado del servidor

Mantener la solicitud de Klaviyo en un único archivo del lado del servidor significa que un cambio de revisión o un encabezado nuevo solo afectan a un lugar, y el Route Handler sigue siendo legible. La función envía un evento al punto de conexión Create Event de Klaviyo y genera un error si algo falla, por lo que quien realiza la llamada decide qué constituye un fallo.

Crea :lib/klaviyo.ts

// lib/klaviyo.ts
const KLAVIYO_EVENTS_URL = 'https://a.klaviyo.com/api/events';

export type ServerEvent = {
  metric: string;
  email: string;
  uniqueId: string;
  time: string;
  value?: number;
  currency?: string;
  properties: Record<string, unknown>;
};

export async function sendEvent(event: ServerEvent): Promise<void> {
  const key = process.env.KLAVIYO_PRIVATE_KEY;
  const revision = process.env.KLAVIYO_REVISION;
  if (!key || !revision) {
    throw new Error('KLAVIYO_PRIVATE_KEY or KLAVIYO_REVISION is not set');
  }

  const res = await fetch(KLAVIYO_EVENTS_URL, {
    method: 'POST',
    headers: {
      Authorization: `Klaviyo-API-Key ${key}`,
      revision,
      'Content-Type': 'application/vnd.api+json',
      Accept: 'application/vnd.api+json',
    },
    body: JSON.stringify({
      data: {
        type: 'event',
        attributes: {
          properties: event.properties,
          time: event.time,
          value: event.value,
          value_currency: event.currency,
          unique_id: event.uniqueId,
          metric: { data: { type: 'metric', attributes: { name: event.metric } } },
          profile: { data: { type: 'profile', attributes: { email: event.email } } },
        },
      },
    }),
  });

  if (!res.ok) {
    throw new Error(`Klaviyo ${res.status}: ${await res.text()}`);
  }
}

unique_ides el campo que hace que esto sea seguro para reintentar. La referencia de Klaviyo indica que "si el unique_id se repite para el mismo perfil y métrica, solo se registrará el primer evento procesado", por lo que enviar el mismo pedido dos veces lo registra una sola vez. Eso es importante porque Webflow reintenta un webhook fallido, tal como depende el paso 6.

6. Añade el Route Handler del webhook de pedido firmado

La ruta acepta el webhook de Webflow y nada más. Comprueba que la solicitud provenga de Webflow antes de leer un solo byte: Webflow envía un encabezado , un HMAC-SHA256 del valor , dos puntos y el cuerpo de la solicitud sin procesar, cifrado con el secreto del webhook.ecomm_new_orderx-webflow-signaturex-webflow-timestamp

La documentación de webhooks de Webflow también aconseja rechazar cualquier solicitud con más de cinco minutos de antigüedad, lo que evita que una solicitud capturada se reproduzca más tarde.

Crea :app/api/webflow-order/route.ts

// app/api/webflow-order/route.ts
import { sendEvent } from '@/lib/klaviyo';

const MAX_AGE_MS = 5 * 60 * 1000; // Webflow's documented replay window

type Money = { unit: string; value: string };
type OrderPayload = {
  orderId: string;
  acceptedOn?: string;
  customerInfo?: { email?: string };
  customerPaid?: Money;
  purchasedItems?: Array<{
    count: number;
    rowTotal: Money;
    productName: string;
    productSlug: string;
    variantId: string;
    variantName?: string;
    variantSKU?: string;
  }>;
};

function hexToBytes(hex: string) {
  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(hex)) return null;
  const bytes = new Uint8Array(hex.length / 2);
  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
  return bytes;
}

// crypto.subtle.verify compares in constant time and runs on Workers and under next dev alike.
async function signatureIsValid(secret: string, timestamp: string, body: string, signature: string) {
  const expected = hexToBytes(signature);
  if (!expected) return false;
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['verify'],
  );
  return crypto.subtle.verify('HMAC', key, expected, encoder.encode(`${timestamp}:${body}`));
}

// Webflow sends amounts as strings in the currency's smallest unit, so "11873" USD is 118.73.
function toAmount(money: Money): number {
  const digits =
    new Intl.NumberFormat('en', { style: 'currency', currency: money.unit }).resolvedOptions()
      .maximumFractionDigits ?? 2;
  return Number(money.value) / 10 ** digits;
}

export async function POST(request: Request) {
  const secret = process.env.WEBFLOW_WEBHOOK_SECRET;
  if (!secret) return new Response('Not configured', { status: 500 });

  const timestamp = request.headers.get('x-webflow-timestamp') ?? '';
  const signature = request.headers.get('x-webflow-signature') ?? '';
  const body = await request.text(); // verify the raw bytes, never a re-serialized copy

  const age = Date.now() - Number(timestamp);
  if (
    !timestamp ||
    !Number.isFinite(age) ||
    Math.abs(age) > MAX_AGE_MS ||
    !(await signatureIsValid(secret, timestamp, body, signature))
  ) {
    return new Response('Invalid signature', { status: 401 });
  }

  let event: { triggerType?: string; payload?: OrderPayload };
  try {
    event = JSON.parse(body);
  } catch {
    return new Response('Invalid JSON', { status: 400 });
  }

  // Acknowledge anything else with 200 so Webflow does not retry it.
  const order = event.payload;
  const email = order?.customerInfo?.email;
  if (event.triggerType !== 'ecomm_new_order' || !order || !email || !order.customerPaid) {
    return new Response('Ignored', { status: 200 });
  }

  const time = order.acceptedOn ?? new Date().toISOString();
  const items = order.purchasedItems ?? [];

  try {
    await sendEvent({
      metric: 'Placed Order',
      email,
      uniqueId: order.orderId,
      time,
      value: toAmount(order.customerPaid),
      currency: order.customerPaid.unit,
      properties: {
        OrderId: order.orderId,
        ItemNames: items.map((item) => item.productName),
        Items: items.map((item) => ({
          ProductName: item.productName,
          ProductID: item.productSlug,
          SKU: item.variantSKU,
          VariantName: item.variantName,
          Quantity: item.count,
          RowTotal: toAmount(item.rowTotal),
        })),
      },
    });

    for (const item of items) {
      await sendEvent({
        metric: 'Ordered Product',
        email,
        uniqueId: `${order.orderId}:${item.variantId}`,
        time,
        value: toAmount(item.rowTotal),
        currency: item.rowTotal.unit,
        properties: {
          OrderId: order.orderId,
          ProductName: item.productName,
          ProductID: item.productSlug,
          SKU: item.variantSKU,
          VariantName: item.variantName,
          Quantity: item.count,
        },
      });
    }
  } catch (err) {
    console.error('klaviyo event failed', err);
    // A 500 makes Webflow retry; unique_id keeps a retry from recording anything twice.
    return new Response('Upstream error', { status: 500 });
  }

  return new Response('OK', { status: 200 });
}

Tres detalles sostienen el diseño. El correo electrónico proviene de , que Webflow escribió cuando se realizó el pedido, por lo que nada de lo que escriba un visitante llega a la clave privada. Un fallo en Klaviyo devuelve un 500 a propósito: la documentación de Webflow dice que un webhook fallido se reintenta hasta tres veces más, con 10 minutos de diferencia, y hace que esos reintentos sean inofensivos.customerInfounique_id

Y los importes se convierten según los decimales propios de la moneda en lugar de dividirse por 100, por lo que un pedido en yenes no presenta un error de factor cien.

7. Registra el webhook y crea los flujos

Envía la aplicación a su repositorio y despliega el entorno. La ruta responde en tu ruta de montaje, por ejemplo, .https://yourstore.com/klaviyo/api/webflow-order

Crea el webhook a través de la API en lugar del panel de control: Webflow señala que "los webhooks creados a través del panel de control no incluirán los encabezados de solicitud necesarios para validar las firmas de las solicitudes", y esta ruta rechaza cualquier cosa que no esté firmada.

Ejecuta esto una vez con tu token de sitio y tu ID de sitio:

curl -X POST "https://api.webflow.com/v2/sites/$SITE_ID/webhooks" \
  -H "Authorization: Bearer $WEBFLOW_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"triggerType":"ecomm_new_order","url":"https://yourstore.com/klaviyo/api/webflow-order"}'

La respuesta incluye un . Para los webhooks creados con un token de sitio, Webflow le da a cada webhook su propio secreto, así que pega ese valor en y vuelve a desplegar, porque una variable modificada solo llega a la aplicación después de un despliegue.secretKeyWEBFLOW_WEBHOOK_SECRET

Realiza un pedido de prueba y comprueba tu perfil en Klaviyo para ver un evento de Pedido Realizado y un evento de Producto Pedido por cada artículo de la línea.

Luego, crea los dos flujos en Klaviyo. Para el abandono de navegación, activa el flujo con Producto Visto, añade un retraso y filtra a cualquiera que haya realizado un pedido desde que comenzó el flujo, lo cual es posible gracias a los eventos de Pedido Realizado.

Para la post-compra, activa el flujo con Pedido Realizado y utiliza o los eventos de Producto Pedido para personalizar tus recomendaciones. Antes de poner cualquiera de los dos en marcha, decide quién puede recibirlo: según la guía de consentimiento de Klaviyo, los perfiles que nunca se suscribieron explícitamente "son elegibles para correos electrónicos de campañas y flujos", así que filtra los flujos según el consentimiento si tu mercado lo requiere.ItemNames

¿Qué causa que los eventos de Klaviyo desde Webflow fallen?

Los eventos del navegador fallan en la página o en la vista del comprador de Klaviyo; los eventos de pedido fallan en la verificación de la firma o en Klaviyo.

Haz coincidir el síntoma con la parte de la construcción a la que pertenece.

Las vistas de productos nunca aparecen en el perfil de Klaviyo del comprador

Causa: El navegador aún no es conocido por Klaviyo. El seguimiento en el sitio de Klaviyo solo registra la actividad de los navegadores que ha identificado o a los que ha asignado una cookie, por lo que descarta las visitas de compradores anónimos en lugar de almacenarlas. Con menos frecuencia, el script nunca se cargó, generalmente porque el código del encabezado no se volvió a publicar o un bloqueador de contenido lo detuvoklaviyo.js.

Solución: Identifica primero el navegador de prueba mediante un formulario de Klaviyo, el formulario de Webflow del paso 3 o un clic desde un correo electrónico de Klaviyo, y luego abre una página de producto. En la pestaña Red (Network), confirma que klaviyo.js se cargó desde static.klaviyo.com y que se envió una solicitud a Klaviyo después de que la página se renderizó.

Si falta el script, vuelve a publicar el sitio después de pegar el código del encabezado y verifica que la clave de seis caracteres coincida con la que aparece en la configuración de claves API de Klaviyo.

La ruta de pedidos devuelve un error 401 para cada entrega de Webflow

Causa: La firma nunca coincide. La razón habitual es un webhook creado en el panel de control de Webflow, que no envía encabezados de firma en absoluto. Otras causas incluyen una WEBFLOW_WEBHOOK_SECRET que pertenece a un webhook diferente o que se guardó sin un nuevo despliegue, y código que analizó y volvió a serializar el cuerpo antes de verificarlo, lo que cambia los bytes que cubre la firma.

Solución: Elimina cualquier webhook creado en el panel de control para ecomm_new_order y créalo con la llamada API del paso 7. Pega la secretKey de esa respuesta en el entorno y vuelve a desplegar. Mantén request.text() como la primera lectura del cuerpo y verifica antes de llamar a JSON.parse. Un pedido de prueba firmado debería devolver entonces un 200 y aparecer en Klaviyo en menos de un minuto.

Los pedidos llegan a la ruta, pero no aparece ningún pedido realizado (Placed Order) en Klaviyo

Causa: La ruta verificó el webhook, pero Klaviyo rechazó el evento, por lo que la ruta devolvió un 500 y registró el motivo. Una clave revocada, o una sin events:write, produce esto. También lo hace una KLAVIYO_REVISION retirada. Webflow reintenta la entrega tres veces, con 10 minutos de diferencia, y luego se detiene.

Solución: Abre los registros de Webflow Cloud para la ruta y lee la línea que comienza con klaviyo event failed; el estado y el mensaje de Klaviyo aparecerán a continuación. Regenera la clave con events:write, o mueve la revisión a una fecha actual, y luego vuelve a desplegar. Los reintentos pendientes tendrán éxito ahora, y unique_id evita que cualquier pedido se cuente dos veces.

La compilación de Webflow Cloud falla después de añadir la ruta

Causa: Una ruta contiene export const runtime = 'edge'. La página de "bring-your-own-app" de Webflow todavía sugiere esa directiva para las rutas API, pero el adaptador OpenNext Cloudflare con el que se compila Webflow Cloud no admite el destino de tiempo de ejecución (runtime) edge de Next.js, por lo que la compilación falla. La línea a veces aparece en código copiado de otros proyectos.

Solución: Busca en el repositorio runtime = 'edge', elimina todas las apariciones y vuelve a desplegar. No hace falta reemplazarlo por nada: el tiempo de ejecución predeterminado es el compatible y la ruta seguirá ejecutándose en Cloudflare Workers.

Ejecuta npm run dev primero para confirmar que la aplicación se inicia localmente y, si la compilación sigue fallando, lee el registro de compilación para encontrar la ruta del archivo que activa el error de tiempo de ejecución.

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

Explora la integración con Klaviyo para ver las opciones sin código, como los formularios de registro propios de Klaviyo.

Mantén los recibos de pedidos y los restablecimientos de contraseña fuera de Klaviyo; son transaccionales y Postmark en Webflow Cloud se encarga de ellos. Para una personalización más profunda más allá de una ruta de webhook, la documentación para desarrolladores de Webflow cubre Webflow Cloud, los webhooks y las API de comercio electrónico.