Cómo sincronizar Webflow CMS con una base de datos externa en Webflow Cloud

La colección que tu equipo de marketing edita en Webflow suele tener que existir también en otros sistemas. Un almacén de informes necesita los mismos casos de estudio, una herramienta interna lee las mismas especificaciones de producto y un servicio de búsqueda requiere los mismos valores de campo en un esquema que él mismo controla.

Una exportación a CSV o un script de copia puntual pueden funcionar al principio, pero enseguida se quedan obsoletos frente a cualquier cambio que haga un editor en el Designer.

Un gestor de rutas de Next.js desplegado en Webflow Cloud puede leer elementos de la colección mediante la API REST de Webflow, asignar una huella digital a cada elemento y actualizar las filas en una base de datos que ya utilices. Un secreto compartido protege la ruta, de modo que cualquier emisor que lo posea, como un programador de tareas o un proceso de CI, puede activar una sincronización cuando lo necesite.

Mantengo el lado de la base de datos detrás de un endpoint HTTP a propósito: no necesita nada que el entorno de ejecución no tenga y sobrevive a cualquier cambio futuro de controlador.

Webflow Cloud ejecuta la aplicación en Cloudflare Workers a través del adaptador OpenNext Cloudflare, por lo que el código se comporta como un entorno de ejecución de Workers. Ese simple hecho determina qué cliente de base de datos puedes usar y qué directiva de Next.js romperá la compilación.

¿Qué necesitas para sincronizar el CMS de Webflow con una base de datos externa?

Necesitas un plan Starter gratuito para empezar. Solo montar la aplicación en un dominio personalizado requiere un plan Premium o superior. Puedes elegir la base de datos, siempre que un entorno de ejecución de Workers pueda acceder a ella; yo confirmaría la compatibilidad antes de comprometerme con un cliente.

Estos son los requisitos:

• Colección del CMS a replicar: Elige la colección cuyos elementos quieras enviar a la base de datos externa.
• Token de la API de Webflow: Un token de API del sitio con el CMS:read ámbito, desde Configuración del sitio > Aplicaciones e integraciones > Acceso a la API, pegado en una variable de entorno.
• Node.js 22 o superior con npm: Webflow Cloud solo admite el gestor de paquetes npm, por lo que los comandos pnpm o yarn en un script de compilación producirán pasos que no funcionarán.
• Next.js 15 o superior: El mínimo para aplicaciones Next.js propias en Webflow Cloud; Astro 6 o 7 y Vite 6.1 o superior también se pueden desplegar.
• Base de datos accesible por HTTP: Una base de datos que acepte escrituras a través de HTTP, con una tabla indexada por el ID del elemento de Webflow. El entorno de ejecución de Workers no abre sockets TCP sin procesar, por lo que pg y mysql2 apuntando directamente a una base de datos no conectarán, independientemente de cómo esté configurada la compilación.

Las rutas que funcionan son un controlador sin servidor que utilice HTTP, la propia capa REST del proveedor o Cloudflare Hyperdrive.

• Secreto de sincronización y emisor: Una cadena larga y aleatoria para el secreto, además del programador de tareas o el proceso de CI que llamará a la ruta para las ejecuciones desatendidas.

Una vez que tengas esto listo, puedes continuar con la construcción.

6 pasos para sincronizar el CMS de Webflow con una base de datos externa en Webflow Cloud

Dos pequeñas bibliotecas se encargan de la verificación de secretos y la obtención de CMS. Un gestor de rutas las utiliza para aplicar hash a cada elemento y realizar una operación upsert, con todo el código orientado al entorno de ejecución de Workers.

1. Prepara la estructura de la aplicación Next.js

Un proyecto  predeterminado ya tiene la forma adecuada para Webflow Cloud. La documentación de Next.js para Webflow Cloud lo define como "Sin adaptador, sin ruta base, sin wrangler.json". Confirma que la versión instalada cumple con el requisito mínimo indicado arriba.create-next-app

Ejecuta estos dos comandos desde el directorio donde guardas tus repositorios:

npx create-next-app@latest webflow-cms-sync --typescript --app
cd webflow-cms-sync

Ahora tienes un proyecto de App Router en TypeScript con un directorio  y un  cuyos scripts utilizan npm. Confirma la estructura inicial tal cual; el resultado que debes verificar antes de continuar es un  limpio localmente.app/package.jsonnpm run build

2. Añade las variables de entorno

El gestor lee cinco valores de  y tres de ellos contienen credenciales. Configura los cinco tanto en  como en el entorno de Webflow Cloud donde se despliega tu aplicación.process.env.env.local

La documentación de variables de entorno de Webflow indica que tanto las variables secretas como las que no lo son están disponibles para el proceso de compilación y para la aplicación desplegada en tiempo de ejecución, por lo que aquí no hace falta ningún paso adicional durante la compilación. Los secretos se ocultan en los registros de compilación, razón por la cual el token y el secreto de sincronización están marcados como tales.

El conjunto completo, indicando cuáles marcar como secretos:

Cada fila es un nombre que tu código leerá de  .  reside en una variable de entorno por una razón práctica: apuntar la sincronización a una colección diferente se convierte en un cambio de configuración en lugar de un nuevo despliegue.process.envWEBFLOW_COLLECTION_ID

Esta compilación necesita muchas menos variables para que puedas añadir una segunda colección más adelante por su nombre

El entorno desplegado y tu  llevan los mismos cinco nombres, así que mantén la ortografía idéntica en ambos. Una vez que el entorno desplegado incluya los cinco con la configuración de secreto correcta, habrás terminado..env.local

3. Escribe la verificación de secretos

El  local carece de  , una extensión de Cloudflare para Web Crypto, mientras que el entorno de ejecución de Workers desplegado sí la proporciona. Por lo tanto, una llamada directa fallará en tu portátil.next devcrypto.subtle.timingSafeEqual

La comparación debe ejecutarse en ambos entornos. Aplicar hash a ambos lados primero también garantiza búferes de igual longitud, lo cual es necesario para la comparación de tiempo constante.

Guárdalo como :lib/verify-secret.ts

const encoder = new TextEncoder();

async function sha256(value: string): Promise<ArrayBuffer> {
  return crypto.subtle.digest('SHA-256', encoder.encode(value));
}

export async function verifySecret(presented: string | null): Promise<boolean> {
  const expected = process.env.SYNC_SECRET;
  if (!presented || !expected) return false;

  // Hash both sides so the buffers are always the same length.
  const a = await sha256(presented);
  const b = await sha256(expected);

  const subtle = crypto.subtle as SubtleCrypto & {
    timingSafeEqual?: (x: ArrayBuffer, y: ArrayBuffer) => boolean;
  };

  if (typeof subtle.timingSafeEqual === 'function') {
    return subtle.timingSafeEqual(a, b);
  }

  // Local next dev: fall back to a byte comparison of the digests.
  const x = new Uint8Array(a);
  const y = new Uint8Array(b);
  let diff = 0;
  for (let i = 0; i < x.length; i++) diff |= x[i] ^ y[i];
  return diff === 0;
}

Ahora tienes un asistente que devuelve solo cuando ambos secretos están presentes y sus resúmenes coinciden. Mantén la protección en su lugar: permite que la misma ruta de código se ejecute en ambos entornos sin necesidad de una bandera de compilación.truetypeof

Impórtalo en una ruta de prueba y envíale un encabezado incorrecto; un sin error lanzado es el resultado que confirma que el respaldo funciona localmente.false

4. Extraer los elementos del CMS

El tiempo de ejecución de Workers cuenta con el estándar , por lo que el contenedor del CMS no requiere ningún SDK ni cliente HTTP exclusivo de Node. El contenedor llama a con un token de portador que incluye el alcance , y debe paginar.fetchGET https://api.webflow.com/v2/collections/{collection_id}/itemsCMS:read

Ese punto de conexión devuelve 25 elementos cuando no pasas ningún , y su máximo documentado es 100, por lo que una única solicitud sin parámetros contra una colección de 400 elementos devuelve 25 filas y no informa de ningún error. La respuesta incluye un objeto con , y , que el bucle a continuación utiliza para saber cuándo ha terminado.limitpaginationlimitoffsettotal

El mismo bucle descarta los elementos archivados y los borradores. Cada elemento contiene y , y un almacén de informes que cuenta los borradores no publicados como contenido activo es un resultado peor que uno que se retrasa.isArchivedisDraft

Crea con este contenido:lib/webflow.ts

export type CmsItem = {
  id: string;
  lastUpdated?: string;
  isArchived?: boolean;
  isDraft?: boolean;
  fieldData: Record<string, unknown>;
};

type ItemsPage = {
  items?: CmsItem[];
  pagination?: { limit: number; offset: number; total: number };
};

const PAGE_SIZE = 100; // documented maximum for this endpoint

export async function fetchCmsItems(): Promise<CmsItem[]> {
  const collectionId = process.env.WEBFLOW_COLLECTION_ID;
  const token = process.env.WEBFLOW_API_TOKEN;
  if (!collectionId || !token) {
    throw new Error('WEBFLOW_COLLECTION_ID and WEBFLOW_API_TOKEN must be set');
  }

  const collected: CmsItem[] = [];
  let offset = 0;
  let total = Infinity;

  while (offset < total) {
    const url = new URL(
      `https://api.webflow.com/v2/collections/${collectionId}/items`,
    );
    url.searchParams.set('offset', String(offset));
    url.searchParams.set('limit', String(PAGE_SIZE));

    const res = await fetch(url, {
      headers: {
        Authorization: `Bearer ${token}`,
        Accept: 'application/json',
      },
    });

    if (res.status === 429) {
      // Respect the documented Retry-After header rather than hammering.
      const wait = Number(res.headers.get('Retry-After') ?? '5');
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }

    if (!res.ok) {
      throw new Error(`Webflow API responded ${res.status}`);
    }

    const payload = (await res.json()) as ItemsPage;
    const page = payload.items ?? [];
    collected.push(...page.filter((item) => !item.isArchived && !item.isDraft));

    total = payload.pagination?.total ?? collected.length;
    if (page.length === 0) break; // defensive: never loop forever
    offset += page.length;
  }

  return collected;
}

Esto proporciona al controlador de ruta la colección completa, solo los elementos publicados y un error claro cuando el token o el ID de la colección están ausentes. La rama es más importante de lo que parece: la API de datos permite 60 solicitudes por minuto en los planes Starter y Basic, y 120 en los planes CMS, Ecommerce y Business, y la página de límites de tasa de Webflow indica que el encabezado "te dirá cuánto tiempo esperar antes de intentar nuevas solicitudes".429Retry-After

Una colección de 900 elementos supone nueve solicitudes secuenciales, lo cual es manejable, pero una sincronización programada que se ejecute junto con cualquier otra cosa que utilice el mismo token no lo es. Una comprobación rápida consiste en registrar en una ruta de prueba y confirmar que coincide con el recuento de elementos publicados que se muestra en el Diseñador.collected.length

5. Calcular la suma de comprobación y actualizar las filas modificadas

SHA-256 de la API estándar WebCrypto crea una huella digital de cada del elemento sin necesidad de una biblioteca de hashing exclusiva de Node. El controlador empaqueta los elementos como filas identificadas por el ID de elemento de Webflow y envía el lote al punto de conexión de tu base de datos.fieldData

La base de datos compara la suma de comprobación entrante con la almacenada y solo sobrescribe una fila cuando son diferentes, por lo que si un editor corrige una errata, las filas no relacionadas permanecen sin cambios.

Coloca el controlador en :app/api/sync/route.ts

import { verifySecret } from '../../../lib/verify-secret';
import { fetchCmsItems, type CmsItem } from '../../../lib/webflow';

type Row = {
  webflow_id: string;
  checksum: string;
  last_updated: string | null;
  data: Record<string, unknown>;
};

async function checksum(item: CmsItem): Promise<string> {
  const bytes = new TextEncoder().encode(JSON.stringify(item.fieldData));
  const digest = await crypto.subtle.digest('SHA-256', bytes);
  return Array.from(new Uint8Array(digest))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');
}

async function upsertRows(rows: Row[]): Promise<void> {
  const url = process.env.DATABASE_UPSERT_URL;
  const token = process.env.DATABASE_TOKEN;
  if (!url || !token) {
    throw new Error('DATABASE_UPSERT_URL and DATABASE_TOKEN must be set');
  }

  const res = await fetch(url, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ rows }),
  });
  if (!res.ok) {
    throw new Error(`Database responded ${res.status}`);
  }
}

export async function POST(request: Request) {
  const ok = await verifySecret(request.headers.get('x-sync-secret'));
  if (!ok) {
    return new Response(JSON.stringify({ error: 'unauthorized' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  const items = await fetchCmsItems();
  const rows: Row[] = [];
  for (const item of items) {
    rows.push({
      webflow_id: item.id,
      checksum: await checksum(item),
      last_updated: item.lastUpdated ?? null,
      data: item.fieldData,
    });
  }

  await upsertRows(rows);
  return new Response(JSON.stringify({ synced: rows.length }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

La ruta ahora rechaza a cualquier llamador que no tenga el encabezado correcto. Luego, obtiene los elementos del CMS y publica filas que contienen sus hashes en una sola solicitud. En el lado de la base de datos, haz que sea la clave de conflicto y escribe la fila solo cuando la suma de comprobación almacenada difiera de la entrante; en SQL, eso es una actualización con una cláusula que compara las sumas de comprobación.webflow_idWHERE

Almaceno todo el objeto en una columna JSON junto con el hash. Este enfoque permite que un campo añadido en el Diseñador llegue a la base de datos sin necesidad de una migración de esquema.fieldData

El límite de seguridad es limitado y explícito. La ruta de sincronización autentica a los llamadores con el del lado del servidor y rechaza cualquier encabezado faltante o incorrecto. Aun así, no tiene límite de tasa, límite de frecuencia de solicitudes, protección de concurrencia ni protección contra ataques de repetición mediante marca de tiempo y nonce.SYNC_SECRET

Configura el programador para evitar ejecuciones superpuestas y añade esos controles si las solicitudes repetidas o concurrentes fueran perjudiciales. La solicitud a la base de datos envía . La implementación del receptor queda fuera de este ejemplo, por lo que la base de datos debe implementar y confirmar la verificación del token, las reglas de autorización, los límites de tasa y el manejo de repeticiones.DATABASE_TOKEN

No se muestra ninguna API de pago, por lo que un límite de gasto no es aplicable aquí; el estado de OAuth y la verificación de la firma de webhook tampoco son aplicables porque este flujo no utiliza ni OAuth ni webhooks. y permanecen en el lado del servidor y no se exponen a través de variables .SYNC_SECRETDATABASE_TOKENNEXT_PUBLIC_

Ejecuta npm run dev, publica en http://localhost:3000/api/sync con el encabezado y busca una {"synced": N} respuesta con filas visibles en tu base de datos.

6. Despliega y ejecuta la primera sincronización

Si falta una variable del controlador, la compilación se realiza correctamente, pero la llamada a la ruta falla porque el código lee las variables dentro del controlador. Confirma que las variables del paso 2 estén configuradas en el entorno de Webflow Cloud antes de desplegar la aplicación en tu sitio.

Este comportamiento es intencionado: un secreto incorrecto genera una respuesta 401 que puedes diagnosticar mientras la compilación sigue disponible para su inspección.

Una vez finalizado el despliegue, activa la ruta desde tu terminal. Sustituye el dominio y la ruta de montaje que Webflow Cloud muestra para tu aplicación:

curl -X POST "https://your-domain.example/your-mount-path/api/sync" \
  -H "x-sync-secret: $SYNC_SECRET"

Deberías recibir {"synced": N} de vuelta, donde N coincide con el número de elementos procesados de la carga útil devuelta, y las filas deberían aparecer en tu base de datos con sus sumas de comprobación. Aplica el manejo de colección completa del paso 4 antes de esperar un recuento de colección completa.

Ejecuta el comando una segunda vez sin cambiar nada en Webflow: la respuesta debería ser idéntica y las marcas de tiempo de las filas de la base de datos deberían permanecer fijas, lo que demuestra que la protección de suma de comprobación funciona.

Luego, edita un elemento en el Diseñador, publica, ejecútalo por tercera vez y solo la suma de comprobación y los datos de esa fila deberían cambiar.

Una respuesta JSON exitosa confirma que la solicitud llegó al controlador y se completó. Apunta tu programador o trabajo de CI al mismo comando con el mismo encabezado, y la sincronización se ejecutará de forma desatendida a partir de ahora.

¿Qué causa que falle una sincronización de la base de datos CMS de Webflow?

Una sincronización puede fallar antes de que se ejecute su controlador cuando la compilación apunta a un entorno de ejecución incompatible o importa una API no disponible. Otros fallos solo aparecen en solicitudes locales o después de una migración de framework.

Los registros de compilación y los seguimientos de pila revelan síntomas distintos, y cada solución se mantiene dentro de las restricciones que establece Webflow Cloud. Empieza por el desajuste del entorno de ejecución, ya que puede hacer que un código de aplicación que de otro modo sería válido falle antes de que se ejecute la sincronización.

El despliegue falla con un error de compilación del adaptador OpenNext

Causa: Añadir export const runtime = 'edge' selecciona un objetivo de entorno de ejecución de Next.js incompatible. La confusión es comprensible porque "edge" significa dos cosas en la misma página de documentación. La documentación describe la plataforma de alojamiento como el despliegue de tu aplicación utilizando el entorno de ejecución Edge.

La página de "trae tu propia aplicación" va más allá y dice que añadas la directiva a tu ruta de API. Después de eso, la frase rompe la compilación.

Solución: Elimina la directiva de cada controlador de ruta y página, y elimina cualquier runtime configuración de segmento que hayas añadido mientras leías la documentación. Los controladores se ejecutan en el despliegue de Workers descrito anteriormente una vez que eliminas la configuración del entorno de ejecución a nivel de archivo.

Recompila localmente con npm run build y confirma que pasa antes de volver a desplegar. Si un compañero vuelve a añadir la línea porque leyó la misma página, explícale la distinción entre plataforma y entorno de ejecución para que la línea se mantenga fuera.

El next dev local lanza subtle.timingSafeEqual is not a function

Este error apunta a una llamada directa a crypto.subtle.timingSafeEqual que omite el asistente entre entornos del paso 3.

Busca en la aplicación timingSafeEqual y redirige cualquier llamada directa antigua a través de verifySecret. El crypto.timingSafeEqual propio de Node desde node:crypto es una función diferente y no es la que falta aquí. Un 401 con un encabezado incorrecto y un 200 con el correcto, ambos bajo npm run dev, confirman el cambio.

El middleware deja de funcionar tras renombrar middleware.ts a proxy.ts

Next 16 renombra el middleware a proxy, y seguir la guía de actualización genera un proxy.ts que no puede ejecutarse en Webflow Cloud. La documentación de personalización de frameworks de Webflow es clara: "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 ejecución de Workers. El archivo proxy se ejecuta en el entorno de Node y no puede optar por Edge, por lo que el cambio de nombre genera un archivo que el entorno de Workers nunca ejecuta.

Si el middleware rechaza las solicitudes sin el encabezado de sincronización antes de que lleguen al controlador, esa protección desaparece y la única señal visible es que el controlador ahora recibe todas las solicitudes.

Fija Next.js 15 para cualquier diseño que dependa de middleware y mantén el archivo con el nombre middleware.ts y su exportación compatible con Edge. Rechazar el codemod en Next 16 no es suficiente por sí solo, porque la convención middleware está obsoleta allí.

El controlador de ruta en app/api/sync/route.ts ya verifica el secreto por sí mismo, por lo que la aplicación permanece segura incluso sin middleware; el middleware aquí solo aporta una capa de comodidad. Tras volver a desplegar, envía una solicitud sin encabezado y confirma que se rechaza en la capa que tenías prevista.

La compilación falla en un controlador de base de datos que importa node:fs

node:fs no está disponible en Webflow Cloud. La documentación de Webflow Cloud establece una fecha de compatibilidad con Workers del 15-04-2025, y node:fs requiere el 01-09-2025 o posterior, por lo que cualquier dependencia que lea un paquete de certificados o un directorio de migraciones desde el disco fallará durante la compilación o en la primera importación.

El fallo proviene de las API que expone el entorno de ejecución. node:path está disponible, por lo que un paquete que solo manipula rutas se instala correctamente mientras que uno que abre archivos no, y ese éxito parcial hace que el error sea difícil de localizar.

Dirige las escrituras a la base de datos a través de un punto final HTTP, como hace la función upsertRows , o elige un controlador cuya documentación indique que funciona en Cloudflare Workers sin acceso al sistema de archivos. Busca en el registro de compilación fallida node:fs para identificar el paquete problemático y luego comprueba si ofrece un punto de entrada para Workers o basado en fetch.

Si la única opción requiere el sistema de archivos, mantén el controlador en el lado de la base de datos del límite HTTP, donde se ejecuta en el entorno que aloje tu punto final, y deja la aplicación de Webflow Cloud como un cliente fetch puro.

Qué puedes construir a continuación con una base de datos externa y Webflow

Una vez que tu colección llega a una base de datos que controlas, las preguntas que el equipo de marketing le ha estado haciendo al CMS se convierten en consultas: qué estudios de caso cambiaron este trimestre y a qué productos les falta un campo.

Yo empezaría con la consulta que elimine la mayor cantidad de comprobaciones manuales del flujo de trabajo de contenido actual del equipo. El CMS de Webflow sigue siendo la superficie de edición donde el equipo publica páginas visualmente, y la sincronización hace que ese contenido esté disponible para cualquier otro sistema de tu parte sin necesidad de un segundo flujo de trabajo de contenido.

La misma estructura de controlador de ruta impulsa una sincronización con la base de datos de Notion cuando el sistema de registro se encuentra totalmente fuera de Webflow. Para una opción específica de base de datos, explora la integración con PostgreSQL.