Cómo crear un sistema de registro de eventos con Webflow y Mailchimp

Las páginas de eventos son uno de los pocos lugares en un sitio de marketing donde la web se convierte realmente en una máquina de generar ingresos. Alguien llega a la página, te da su correo electrónico y espera una confirmación en cuestión de segundos. Cuando esa gestión es manual o pasa por una hoja de cálculo, el seguimiento llega tarde y se pierden registros.

Webflow te da la página y el formulario. Mailchimp te da la audiencia, el correo de confirmación y la secuencia de recordatorios. Lo que ocurre entre ambos es una decisión, y la respuesta correcta depende de cuánto control necesites sobre lo que sucede después de que alguien hace clic en enviar.

Esta guía cubre las tres rutas de conexión y luego desarrolla la que te da control total: un Route Handler ejecutándose en Webflow Cloud que escribe al inscrito directamente en una audiencia de Mailchimp.

¿Qué necesitas para conectar Webflow y Mailchimp?

Cuatro cosas, y solo una de ellas tiene coste: un sitio de Webflow con un formulario, una cuenta de Mailchimp con una audiencia, una clave API y un proyecto de Webflow Cloud si quieres la ruta programada. No se requiere un plan de pago de Webflow para empezar.

Aquí tienes la lista completa antes de tocar nada de código:

• Un sitio de Webflow con una página de eventos publicada y un formulario
• Una cuenta de Mailchimp con al menos una audiencia. La disponibilidad de funciones varía según el plan, así que consulta los precios de Mailchimp para ver qué incluye tu nivel
• Una clave API de Mailchimp, que puedes generar desde la configuración de tu cuenta
• Para la ruta programada, un proyecto de Webflow Cloud ejecutando una aplicación Next.js, además de Node.js 22.13.0 o superior en local, el requisito mínimo establecido por Webflow CLI 2.x

Webflow Cloud está disponible desde el plan gratuito Starter en adelante, y montar tu aplicación en un dominio personalizado requiere un plan de sitio Premium o superior. Una vez que tengas esto, todo el flujo se reduce a un único Route Handler y a la forma en que Mailchimp identifica a un contacto. Aquí te explicamos cómo.

3 formas de conectar un formulario de Webflow a Mailchimp

Las tres rutas terminan con un contacto en tu audiencia. Se diferencian en un aspecto: cuánto control tienes sobre el envío antes de que llegue allí.

El diagrama muestra las tres opciones claramente. Una acción de formulario nativa envía los datos directamente a Mailchimp, una plataforma de automatización actúa como paso intermedio alojado, y tu propio servidor recibe el envío y llama a la API directamente. Esta tabla es la versión resumida de la misma decisión:

El resto de esta guía construye la tercera ruta. Es la única donde un registro puede hacer más de una cosa, que es lo que un evento necesita en cuanto añades límites de capacidad, listas de espera o un registro en tu propia base de datos.

6 pasos para crear un sistema de registro de eventos en Webflow

La construcción consiste en una audiencia de Mailchimp, un gestor de rutas y un componente de formulario. El gestor de rutas hace el trabajo interesante, porque Mailchimp identifica los contactos mediante un correo electrónico cifrado en lugar de uno normal.

1. Crea la audiencia y los campos de combinación en Mailchimp

Empieza en Mailchimp en lugar de en el código, porque cada campo que planees enviar debe existir antes de que la API lo acepte. Abre Audience, luego Settings, y después Audience fields y etiquetas *|MERGE|*.

La etiqueta de combinación es el nombre que usas en la llamada a la API, no la etiqueta que se muestra en la interfaz. Mantén esta lista corta: cada campo que añades es un campo que alguien tiene que rellenar, y los formularios de registro pierden gente con cada dato extra. Nombre, apellidos y correo electrónico cubren la mayoría de los eventos.

Anota el ID de la audiencia mientras estás aquí. Aparece en Audience, luego en el menú desplegable More options, después en Audience settings, en una fila etiquetada Audience ID. La API se refiere a él como el ID de la lista. Deberías terminar este paso con dos valores anotados: el ID de la audiencia y las etiquetas de combinación que pretendes completar.

2. Genera una clave API y encuentra tu centro de datos

Genera una clave API desde tu cuenta de Mailchimp: abre tu perfil, luego el menú desplegable Extras y después API keys. La clave tiene los permisos del usuario que la creó, así que créala desde una cuenta con el acceso que quieres que tenga la integración, no desde un inicio de sesión de administrador personal que podrías eliminar más tarde.

Cada solicitud a la API de Mailchimp va a un centro de datos específico para tu cuenta. La URL raíz es https://<dc>.api.mailchimp.com/3.0/, donde <dc> es un valor como us6. El prefijo es el segmento después del último guion en tu clave API, por lo que el código a continuación lo deriva en lugar de pedirte que lo escribas manualmente. Tanto la estructura de la URL como los dos estilos de autenticación aceptados se explican en los fundamentos de la API de Mailchimp. Al final de este paso, tendrás una clave cuyo sufijo te indica a qué host llamar.

3. Almacena las credenciales como variables de entorno

Ambos valores pertenecen a tu entorno de Webflow Cloud en lugar de al repositorio.

Abre las variables de entorno y añádelas, marcando la clave de API como secreta:

MAILCHIMP_API_KEY=your-key-here-us6
MAILCHIMP_LIST_ID=57afe96172

Webflow Cloud pone las variables de entorno a disposición de la compilación y de la aplicación desplegada en tiempo de ejecución, y oculta los valores secretos de los registros de compilación. Léelas dentro del controlador en lugar de en el nivel superior del módulo, para que el valor se resuelva en el contexto de la solicitud. Un despliegue después de añadirlas es lo que las hace efectivas.

4. Crea el controlador de rutas de registro

Aquí es donde aparece la restricción interesante. El identificador canónico de Mailchimp para un contacto es el hash MD5 del correo electrónico en minúsculas, aunque el punto de conexión también acepta una dirección de correo electrónico simple o un ID de contacto. El hash está documentado en la referencia de métodos y parámetros de Mailchimp, y el uso de hash significa que puedes dirigirte a un contacto sin incluir el correo electrónico en la ruta de la solicitud.

MD5 no forma parte del estándar WebCrypto, así que este es el punto donde fallan muchos despliegues en el borde. Cloudflare Workers, el entorno de ejecución detrás de Webflow Cloud, admite MD5 crypto.subtle.digest específicamente para comunicarse con sistemas que lo requieren. La documentación de Web Crypto de Cloudflare lo enumera y añade una advertencia que vale la pena repetir: MD5 es un algoritmo débil y nunca se debe confiar en él para la seguridad.

Aquí funciona como un identificador, no como una protección.

// app/api/register/route.ts
import { NextRequest, NextResponse } from 'next/server'

type RegistrationBody = {
  email: string
  firstName?: string
  lastName?: string
}

// Mailchimp identifies a contact by the MD5 hash of its lowercase email.
async function subscriberHash(email: string): Promise<string> {
  const bytes = new TextEncoder().encode(email.trim().toLowerCase())
  const digest = await crypto.subtle.digest('MD5', bytes)
  return [...new Uint8Array(digest)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
}

export async function POST(request: NextRequest) {
  const { email, firstName, lastName } =
    (await request.json()) as RegistrationBody

  if (!email) {
    return NextResponse.json({ error: 'Email is required' }, { status: 400 })
  }

  // Read secrets inside the handler, not at module top level.
  const apiKey = process.env.MAILCHIMP_API_KEY
  const listId = process.env.MAILCHIMP_LIST_ID

  if (!apiKey || !listId) {
    return NextResponse.json(
      { error: 'Mailchimp is not configured' },
      { status: 500 }
    )
  }

  // Normalise once so the hash and the body always agree.
  const normalizedEmail = email.trim().toLowerCase()

  // The data center is the segment after the final dash in the key.
  const dc = apiKey.split('-').pop()
  const hash = await subscriberHash(normalizedEmail)

  const response = await fetch(
    `https://${dc}.api.mailchimp.com/3.0/lists/${listId}/members/${hash}`,
    {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        email_address: normalizedEmail,
        status_if_new: 'pending',
        merge_fields: { FNAME: firstName ?? '', LNAME: lastName ?? '' },
      }),
    }
  )

  if (!response.ok) {
    // A gateway error may not be JSON, so never assume it parses.
    const detail = await response.json().catch(() => null)
    return NextResponse.json(
      { error: (detail as { title?: string })?.title ?? 'Registration failed' },
      { status: 502 }
    )
  }

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

Hay tres cosas en este controlador que son deliberadas. La solicitud utiliza PUT en lugar de POST, porque el punto de conexión de añadir o actualizar crea el contacto si no existe y lo actualiza si ya existe. Un POST a la colección de miembros está documentado para añadir un nuevo miembro, por lo que Mailchimp te indica que utilices añadir o actualizar siempre que no sepas si el contacto ya existe. Cada registro repetido es ese caso.

El estado es status_if_new: 'pending', lo que deja a un nuevo contacto a la espera de la confirmación de suscripción en lugar de suscribirlo directamente. Este es el ajuste que más vale la pena defender: registrarse en un evento es dar consentimiento para recibir información sobre ese evento, no consentimiento para una lista de marketing, y tratar ambos como lo mismo es la forma en que la reputación del remitente se degrada. Si tienes un consentimiento explícito y por separado, cámbialo a subscribed de forma deliberada y no por defecto.

El cuerpo del error de Mailchimp se lee antes de responder y el formulario lo muestra, por lo que un fallo muestra el propio mensaje de Mailchimp en lugar de un 500 genérico. Despliega esto y una solicitud POST a la ruta debería devolver { ok: true } con el contacto visible en tu audiencia.

5. Envía el formulario a tu controlador de rutas

El componente cliente recopila los campos y envía JSON al controlador que acabas de crear. Webflow Cloud inyecta la ruta base en el momento de la compilación, por lo que ya no tienes que declararla en next.config. Un fetch del lado del cliente no se reescribe automáticamente para ti.

Pasa la ruta de montaje a través de una variable NEXT_PUBLIC_BASE_PATH y añade el prefijo a la llamada:

// app/components/RegistrationForm.tsx
'use client'

import { useState } from 'react'

// Webflow Cloud injects the base path at build time, so read the mount
// path from an environment variable rather than from next.config.
const baseUrl = process.env.NEXT_PUBLIC_BASE_PATH || ''

export default function RegistrationForm() {
  const [status, setStatus] = useState<'idle' | 'sending' | 'done' | 'error'>('idle')
  const [error, setError] = useState('')

  async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = new FormData(event.currentTarget)
    setStatus('sending')

    try {
      const res = await fetch(`${baseUrl}/api/register`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          email: form.get('email'),
          firstName: form.get('firstName'),
          lastName: form.get('lastName'),
        }),
      })

      if (!res.ok) {
        const detail = await res.json().catch(() => null)
        setError(detail?.error ?? 'Registration failed')
        setStatus('error')
        return
      }
      setStatus('done')
    } catch {
      setStatus('error')
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="firstName" placeholder="First name" />
      <input name="lastName" placeholder="Last name" />
      <input name="email" type="email" required placeholder="Email" />
      <button type="submit" disabled={status === 'sending'}>
        {status === 'sending' ? 'Registering...' : 'Register'}
      </button>
      {status === 'done' && <p>Check your inbox to confirm your place.</p>}
      {status === 'error' && <p>{error || 'Something went wrong. Please try again.'}</p>}
    </form>
  )
}

El texto de confirmación es más importante de lo que parece. Debido a que el contacto se crea como pendiente, el registro no se completa hasta que hacen clic en el enlace de su bandeja de entrada, por lo que un mensaje que diga "ya estás registrado" sería incorrecto. Al enviar el formulario, el visitante debería permanecer en la página con un mensaje que le indique que revise su bandeja de entrada.

6. Confirma que el contacto llegó y luego segmentalo

Envía un registro de prueba y abre la audiencia en Mailchimp. Aparecerá un contacto pendiente de inmediato, con los campos de combinación completados y un estado que cambiará una vez que se haga clic en el enlace de confirmación.

Para múltiples eventos en una misma audiencia, las etiquetas son el mecanismo que los mantiene separados, y la guía de etiquetas de Mailchimp cubre cómo aplicarlas a través de la API. Etiquetar por evento significa que una audiencia puede gestionar una secuencia de recordatorios por evento sin necesidad de una lista separada para cada uno. Una vez que veas al contacto pendiente con la etiqueta correcta, el flujo de trabajo estará funcionando de principio a fin.

¿Qué causa que el registro de Webflow a Mailchimp falle? Consejos para solucionar problemas

Cuatro fallos explican casi todo: la directiva del entorno de ejecución en el borde, una clave faltante o que no coincide, el estado pendiente confundido con un error y el uso del método HTTP incorrecto para un registro repetido.

La compilación falla después de añadir el controlador de rutas

Causa: una directiva en el archivo de ruta. Webflow Cloud despliega Next.js a través del export const runtime = 'edge'adaptador OpenNext de Cloudflare, que no es compatible con el entorno de ejecución edge de Next.js.

Solución: elimina la línea. Los controladores de rutas ya se ejecutan en el entorno de ejecución de Workers sin ella, y la compilación tendrá éxito en el siguiente despliegue.

Mailchimp devuelve un error 401 Unauthorized tras el despliegue, pero funciona en local

Causa: la clave existe en tu archivo de entorno local pero no en el entorno desplegado, o se añadió después del último despliegue. Usar una clave de una cuenta con el prefijo del centro de datos de otra también devuelve un 401 en lugar de un error más claro.

Solución: añade la variable en el entorno de Webflow Cloud, vuelve a desplegar y confirma que el prefijo en la URL de la solicitud coincida con el sufijo de la clave que pegaste.

Los registros se realizan correctamente, pero nadie aparece suscrito

Causa: este es el comportamiento esperado de , no un error. El contacto existe y está esperando a que haga clic en la confirmación.pending

Solución: ninguna, a menos que tu evento requiera realmente una suscripción inmediata y tengas el consentimiento para hacerlo. En ese caso, cambia el estado deliberadamente e indícalo en el formulario.

El primer registro funciona y el segundo falla

Causa: estás usando hacia la colección de miembros en lugar de hacia el recurso del miembro. El endpoint de la colección solo está documentado para añadir un nuevo miembro.POSTPUT

Solución: cambia a la URL del miembro con hash usando , que realiza un upsert en lugar de un insert y soluciona el problema de forma permanente. Vale la pena detectar esto durante las pruebas y no en producción, ya que solo aparece en el segundo registro desde la misma dirección, y una prueba de una sola pasada nunca lo revelará. Regístrate dos veces antes de dar por terminado el flujo.PUT

Qué puedes construir a continuación con Mailchimp y Webflow Cloud

El Route Handler es el punto único por el que pasa un registro a través de tu propio código, lo que hace posible el resto: guardar al registrado en una base de datos para controlar límites de capacidad, comprobar una lista de espera antes de confirmar o enviar una notificación interna al mismo tiempo.

El mismo patrón se aplica a cualquier proveedor transaccional, y nuestra guía de formularios de contacto con SendGrid cubre esa variante, incluida la protección contra spam mediante honeypot, que un formulario de evento en una página pública necesitará tarde o temprano. Si prefieres no mantener el código en absoluto, la integración de Webflow y Mailchimp cubre la ruta de conexión nativa del diagrama anterior.

Para una personalización más profunda más allá de lo que permite la integración nativa, la documentación para desarrolladores de Webflow cubre los Route Handlers, los bindings de almacenamiento y el resto del runtime de Webflow Cloud.