Cómo añadir verificación SMS de doble factor a Webflow con Twilio

La verificación de dos factores es una tarea de servidor que se hace pasar por un campo de formulario. El código que escribe el usuario es fácil; lo difícil es generarlo, enviarlo, comprobarlo y aplicar límites de caducidad e intentos sin confiar nunca en el navegador.

Webflow Cloud ejecuta tu aplicación como un Cloudflare Worker, el componente del lado del servidor que hace esto posible. Tus credenciales de Twilio residen en variables de entorno, el código se envía y se comprueba desde los Route Handlers, y el resultado vuelve al navegador como un simple sí o no.

La API Verify de Twilio hace el trabajo pesado: gestiona el código, su duración de 10 minutos y el límite de intentos, para que nunca tengas que almacenar o comparar el código original tú mismo.

Hay un detalle de tiempo de ejecución que define toda la estructura. La biblioteca auxiliar de Node de Twilio incluye node:net y no se ejecuta en el entorno de ejecución de Workers, por lo que cada llamada a Twilio aquí es un simple fetch contra la API REST de Verify. Ese es el enfoque que Cloudflare documenta para llamar a Twilio desde un Worker, y mantiene la integración libre de dependencias.

En esta guía, construiremos el flujo completo en seis pasos, desde un servicio Verify y un cliente compatible con Workers hasta el envío de un código, su comprobación, la emisión de una sesión firmada y la configuración de la interfaz de dos pasos.

¿Qué necesitas para añadir la verificación por SMS de dos factores a Webflow con Twilio?

Necesitas una aplicación Next.js en Webflow Cloud y una cuenta de Twilio con un servicio Verify. El servicio Verify es la pieza más importante porque genera y valida los códigos, por lo que tu propio código nunca tiene que hacerlo.

Aquí tienes la lista completa de lo que necesitas:

• Un proyecto de Webflow Cloud ejecutando una aplicación Next.js, ya sea desplegada o en desarrollo local
• Una cuenta de Twilio con un servicio Verify activo (console.twilio.com)
• Tu SID de cuenta de Twilio y tu token de autenticación
• Tu SID de servicio de Verify (empieza por VA)
• Un secreto de servidor para firmar la sesión posterior a la verificación
• Una sesión iniciada existente que ya conozca el número de teléfono del usuario, ya que el segundo factor se comprueba con el número de su cuenta en lugar de uno escrito en el formulario
• Un enlace de clave-valor llamado SESSION_KV para el límite de envío del lado del servidor
• Node.js 22.13.0 o superior de forma local, el requisito mínimo para Webflow CLI 2.0

Si ya gestionas el inicio de sesión mediante autenticación Auth0 en un sitio de Webflow, el segundo factor se añade encima: el usuario se autentica primero y luego supera el paso del SMS antes de acceder a cualquier información sensible.

Y si tu aplicación ya envía SMS salientes como lo hace una configuración de SMS transaccionales en Webflow Cloud, estás reutilizando la misma cuenta de Twilio, solo que con una API diferente.

6 pasos para añadir la verificación por SMS de dos factores a Webflow con Twilio

El flujo sigue la experiencia del usuario: configurar el servicio, conectarse a él, enviar un código, verificarlo, recordar que fue validado y, finalmente, mostrar un formulario en la página. Los pasos uno y dos son la base. Del tres al seis conforman el ciclo de verificación.

Esta es la secuencia que sigo en cada proyecto de Webflow Cloud que protege una acción mediante SMS:

• Crea un servicio de Twilio Verify y configura tus credenciales
• Crea un cliente de Twilio Verify que se ejecute en el entorno de Workers
• Envía el código desde un Route Handler
• Verifica el código desde un Route Handler
• Emite una sesión de verificación firmada con Web Crypto
• Construye la interfaz de verificación en dos pasos

Cada llamada a Twilio se ejecuta en un Route Handler, por lo que tu Account SID y tu Auth Token permanecen en el servidor y nunca llegan al navegador.

1. Crea un servicio de Twilio Verify y configura tus credenciales

Twilio Verify está vinculado a un servicio, un contenedor que almacena la configuración de tus códigos y te proporciona un Service SID que comienza con VAVA. Créalo primero, ya que cada llamada de envío y verificación pasa a través de él.

En la consola de Twilio, abre Verify, crea un nuevo servicio, asígnale un nombre amigable (de hasta 30 caracteres; aparecerá en el cuerpo del mensaje de verificación, no como el remitente) y copia el Service SID. Tu Account SID y tu Auth Token se encuentran en el panel de control de la consola.

Añade los tres a .env.env.local y a tu proyecto de Webflow Cloud en las variables de entorno, marcando el Auth Token y el secreto de sesión como Secrets para que permanezcan cifrados:

TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_VERIFY_SERVICE_SID=your_verify_service_sid
SESSION_SECRET=a_long_random_string

Ninguno de ellos lleva el prefijo NEXT_PUBLIC_NEXT_PUBLIC_. El navegador nunca los toca; solo los Route Handlers los leen desde process.envprocess.env, que es donde Webflow Cloud inyecta las variables de entorno y los Secrets durante la ejecución.

2. Crea un cliente de Twilio Verify que se ejecute en el entorno de Workers

Como la biblioteca de Node de Twilio no funciona en Workers, envuelve la llamada REST en una pequeña utilidad en lugar de repetir el encabezado de autenticación en cada controlador. Twilio Verify se autentica mediante HTTP Basic con tu Account SID y Auth Token, y sus endpoints aceptan cuerpos codificados como formulario.

Crea :lib/twilio.ts

// lib/twilio.ts

const VERIFY_BASE = 'https://verify.twilio.com/v2'

// The Twilio Node helper pulls in node:net and fails on the Workers runtime,
// so every call is a fetch against the Verify REST API with Basic auth.
export async function verifyFetch(
  path: string,
  params: Record<string, string>
): Promise<Response> {
  const auth = btoa(
    `${process.env.TWILIO_ACCOUNT_SID}:${process.env.TWILIO_AUTH_TOKEN}`
  )

  return fetch(
    `${VERIFY_BASE}/Services/${process.env.TWILIO_VERIFY_SERVICE_SID}${path}`,
    {
      method: 'POST',
      headers: {
        Authorization: `Basic ${auth}`,
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams(params),
    }
  )
}

Dos detalles hacen el trabajo pesado. El cuerpo se codificaapplication/x-www-form-urlencoded con URLSearchParamsURLSearchParams, porque eso es lo que esperan los endpoints de Verify; enviar JSON es la razón más común por la que falla una primera llamada.

Y btoa()btoa construye el encabezado de autenticación básica a partir de tus credenciales, de modo que el manejo del token reside en un solo lugar y ningún controlador ve nunca el Auth Token sin procesar.

3. Envía el código desde un Route Handler

La primera mitad del flujo envía un código de un solo uso al teléfono del usuario. Twilio Verify genera el código, entrega el SMS y devuelve un estado pendingpending. Tú nunca ves el código, y de eso se trata.

El origen del número de teléfono determina si todo este esfuerzo merece la pena. Si el controlador lo toma del cuerpo de la solicitud, un atacante puede enviar su propio número, superar la verificación y llevarse un token que tu aplicación tratará como prueba válida. Por eso, el número debe provenir de la sesión iniciada y el controlador no debe leer nada del cuerpo de la solicitud. Una función auxiliar que identifique al usuario actual es la pieza clave de este rompecabezas:

Crea lib/auth.ts, y luego el controlador de envío:

// lib/auth.ts
import { cookies } from 'next/headers'
import { verifyToken } from '@/lib/session'

// Whatever your login flow already sets. The payload carries the user id and the
// phone number on record, both written server-side at sign-in, so a caller can
// never substitute a different number later in the flow.
export type AppUser = { userId: string; phone: string }

export async function requireUser(): Promise<AppUser | null> {
  const jar = await cookies()
  const token = jar.get('app_session')?.value
  if (!token) return null

  const payload = await verifyToken(token)
  if (!payload) return null

  const [userId, phone] = payload.split('|')
  return userId && phone ? { userId, phone } : null
}

A continuación, el controlador de envío propiamente dicho:

// app/api/2fa/start/route.ts
import { NextResponse } from 'next/server'
import { getCloudflareContext } from '@opennextjs/cloudflare'
import { verifyFetch } from '@/lib/twilio'
import { requireUser } from '@/lib/auth'

const MAX_SENDS = 3
const WINDOW_SECONDS = 15 * 60

export async function POST() {
  // Nothing is read from the request body. The number comes from the signed
  // session, so a caller cannot start a verification for someone else's phone.
  const user = await requireUser()
  if (!user) {
    return NextResponse.json({ error: 'Sign in first' }, { status: 401 })
  }

  // Server-side send cap, keyed to the user. A throttled button is not a limit,
  // because anyone can call this route directly.
  const { env } = getCloudflareContext()
  const bucket = `2fa:sends:${user.userId}`
  const used = Number((await env.SESSION_KV.get(bucket)) ?? '0')
  if (used >= MAX_SENDS) {
    return NextResponse.json({ error: 'Too many code requests' }, { status: 429 })
  }
  await env.SESSION_KV.put(bucket, String(used + 1), {
    expirationTtl: WINDOW_SECONDS,
  })

  const res = await verifyFetch('/Verifications', {
    To: user.phone,
    Channel: 'sms',
  })

  if (!res.ok) {
    return NextResponse.json({ error: 'Could not send code' }, { status: 502 })
  }

  const { status } = (await res.json()) as { status: string }
  return NextResponse.json({ status }) // "pending" once the SMS is on its way
}

Como el número se lee de la sesión y no de la solicitud, no hay datos de usuario que validar aquí; guárdalo en formato E.164 al registrarte y la llamada de envío siempre será correcta. El límite de envíos es lo que requiere tu atención. Twilio Verify limita los intentos de verificación al mismo número y ejecuta Fraud Guard por defecto, pero eso protege un destino, no tu controlador. Por eso el controlador anterior requiere una sesión y cuenta los envíos por usuario en el almacén de clave-valor antes de llamar a Twilio. Sin un límite en el servidor, un atacante podría usar un controlador abierto con miles de números y cargarte el coste de cada mensaje.

4. Comprueba el código desde un controlador de ruta

La segunda parte valida la entrada del usuario. Envías el teléfono y el código al endpoint VerificationCheck, y Twilio devuelve approved cuando coinciden. Una verificación desaparece una vez aprobada o cuando caduca. Lo mismo ocurre cuando se agotan los intentos de comprobación; en ese caso, el endpoint responde con un 404 en lugar de un estado, así que trátalo como un caso independiente.

Crea :app/api/2fa/check/route.ts

// app/api/2fa/check/route.ts
import { NextResponse, type NextRequest } from 'next/server'
import { verifyFetch } from '@/lib/twilio'
import { signToken } from '@/lib/session'
import { requireUser } from '@/lib/auth'

export async function POST(request: NextRequest) {
  const user = await requireUser()
  if (!user) {
    return NextResponse.json({ error: 'Sign in first' }, { status: 401 })
  }

  // Only the code comes from the browser. The number is the one on the session.
  const { code } = (await request.json()) as { code: string }

  const res = await verifyFetch('/VerificationCheck', {
    To: user.phone,
    Code: code,
  })

  // A consumed, expired, or over-attempted verification returns 404.
  if (res.status === 404) {
    return NextResponse.json(
      { approved: false, reason: 'expired' },
      { status: 410 }
    )
  }

  const { status } = (await res.json()) as { status: string }
  if (status !== 'approved') {
    return NextResponse.json({ approved: false }, { status: 401 })
  }

  // The token names the user who cleared the second factor, so a protected route
  // can compare it against the session it already has.
  const token = await signToken(`2fa:${user.userId}`, 15 * 60)

  const response = NextResponse.json({ approved: true })
  response.cookies.set('2fa', token, {
    httpOnly: true,
    secure: true,
    sameSite: 'strict',
    maxAge: 15 * 60,
  })
  return response
}

El código nunca se compara en tu propio código; Twilio se encarga de esa comprobación, lo cual garantiza que los límites de caducidad e intentos se respeten. Lo único que persistes es el resultado, y lo haces como un token firmado en el siguiente paso, para que una solicitud posterior no pueda simplemente alegar que fue aprobada.

5. Emite una sesión de verificación firmada con Web Crypto

Una cookie que solo diga 2fa=true es fácil de falsificar, y un token vinculado a un número de teléfono proporcionado por el navegador no es mucho mejor. El token a continuación identifica al usuario que superó el factor, de modo que una ruta protegida pueda contrastarlo con la sesión existente. En su lugar, firma una pequeña carga útil con un secreto del servidor para que solo tu código pueda generar un token válido, y verifícalo en cualquier ruta que requiera un segundo factor superado.

En Webflow Cloud, la firma utiliza la API Web Crypto, que la documentación de compatibilidad de Node.js de Webflow recomienda sobre crypto de Node para el hashing y la firma.

Crea :lib/session.ts

// lib/session.ts

async function key(): Promise<CryptoKey> {
  return crypto.subtle.importKey(
    'raw',
    new TextEncoder().encode(process.env.SESSION_SECRET!),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign', 'verify']
  )
}

function toHex(buf: ArrayBuffer): string {
  return Array.from(new Uint8Array(buf))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('')
}

// Sign "payload.expiry" with HMAC-SHA256 so the token cannot be forged.
export async function signToken(
  payload: string,
  ttlSeconds: number
): Promise<string> {
  const exp = Math.floor(Date.now() / 1000) + ttlSeconds
  const body = `${payload}.${exp}`
  const sig = await crypto.subtle.sign(
    'HMAC',
    await key(),
    new TextEncoder().encode(body)
  )
  return `${body}.${toHex(sig)}`
}

// Verify the token and its expiry, then hand back the payload it carried.
export async function verifyToken(token: string): Promise<string | null> {
  const cut = token.lastIndexOf('.')
  if (cut < 0) return null
  const body = token.slice(0, cut)
  const sig = token.slice(cut + 1)

  const expAt = body.lastIndexOf('.')
  const exp = Number(body.slice(expAt + 1))
  if (!exp || exp < Math.floor(Date.now() / 1000)) return null

  const expected = await crypto.subtle.sign(
    'HMAC',
    await key(),
    new TextEncoder().encode(body)
  )

  // Constant-time compare so the signature cannot be probed byte by byte.
  const want = toHex(expected)
  if (want.length !== sig.length) return null
  let diff = 0
  for (let i = 0; i < want.length; i++) diff |= want.charCodeAt(i) ^ sig.charCodeAt(i)
  if (diff !== 0) return null

  return body.slice(0, expAt)
}

Lee la cookie 2fa y llama a verifyToken al inicio de cualquier controlador de ruta protegido. Rechaza la solicitud si devuelve null, y recházala con la misma firmeza si la carga útil no es 2fa: seguida por el ID del usuario con el que la solicitud ya está autenticada. Una firma válida solo demuestra que algún usuario superó el factor; el ID es lo que demuestra que fue este usuario en concreto. Como el token lleva su propia fecha de caducidad y una firma, una cookie caducada o manipulada fallará la comprobación sin necesidad de consultar la base de datos.

6. Crea la interfaz de verificación en dos pasos

El front-end consta de dos estados en un único componente de cliente: solicitar un código y luego introducirlo. No hay campo de teléfono, porque el servidor ya conoce el número y aceptar uno aquí dejaría la decisión en manos del navegador. El widget solo llama a tus propios controladores de ruta, por lo que ninguna credencial o código de Twilio llega nunca a él.

Crea :app/components/TwoFactor.tsx

// app/components/TwoFactor.tsx
"use client";

import { useState } from "react";

export default function TwoFactor({ baseUrl = "" }: { baseUrl?: string }) {
  const [code, setCode] = useState("");
  const [sent, setSent] = useState(false);
  const [message, setMessage] = useState("");

  async function sendCode() {
    // No phone field. The server sends to the number on the signed-in account.
    const res = await fetch(`${baseUrl}/api/2fa/start`, { method: "POST" });
    setSent(res.ok);
    setMessage(
      res.ok
        ? "We sent a code to the number on your account."
        : "Could not send a code right now."
    );
  }

  async function checkCode() {
    const res = await fetch(`${baseUrl}/api/2fa/check`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code }),
    });
    setMessage(res.ok ? "Verified." : "Wrong or expired code.");
  }

  return (
    <div>
      {!sent ? (
        <button onClick={sendCode}>Send code</button>
      ) : (
        <>
          <input
            value={code}
            onChange={(e) => setCode(e.target.value)}
            placeholder="123456"
            inputMode="numeric"
          />
          <button onClick={checkCode}>Verify</button>
        </>
      )}
      <p>{message}</p>
    </div>
  );
}

Pasa baseUrl desde el basePath de tu aplicación, porque una aplicación de Webflow Cloud se monta en una ruta como /app, por lo que una ruta /api/2fa/start simple se resolvería contra la raíz incorrecta. Con el componente montado, el usuario introduce un teléfono, recibe un mensaje, escribe el código y la cookie firmada del paso cinco traslada ese estado de verificación al resto de tu aplicación.

¿Qué puede fallar en la verificación por SMS de Twilio en Webflow Cloud?

La mayoría de los fallos se deben a unas pocas causas predecibles:

• La librería de Node de Twilio se importa en un controlador de ruta
• Autenticación básica creada con credenciales incorrectas
• Un código que ha caducado o ha agotado los intentos
• Un número de teléfono que no está en formato E.164

Cada uno suele fallar con un error genérico, así que los síntomas a continuación los relacionan con una causa.

La compilación falla o el controlador genera un error en cualquier importación de Twilio

Se importó la biblioteca auxiliar de Twilio para Node, pero depende de y otros elementos internos de Node que el entorno de ejecución de Workers no proporciona, por lo que falla en el momento de la compilación o en la primera solicitud.node:net

Elimina el paquete de tus controladores y llama a la API REST de Verify con , como hace la utilidad . Todo lo que necesita Verify, enviar y verificar códigos, es un simple HTTPS POST, por lo que no se requiere ningún SDK en el edge.twiliofetchlib/twilio.ts

Cada llamada a Twilio devuelve un 401 Unauthorized

El encabezado de autenticación básica se crea con valores incorrectos. Verify se autentica con tu Account SID y Auth Token, no con el Service SID de Verify, que debe ir en la ruta de la URL.

Confirma que y coincidan con el panel de control, que el Service SID que comienza con se use solo en la ruta y que los tres estén configurados para el entorno implementado, no solo en un archivo local. Vuelve a copiar el Auth Token si se rotó, ya que el valor anterior deja de funcionar inmediatamente.TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKENVA.env

VerificationCheck devuelve un 404 en lugar de un estado

La verificación ya no existe. Twilio elimina la verificación una vez que se aprueba, cuando caduca después de 10 minutos o cuando se agotan los intentos de verificación. Las comprobaciones posteriores devuelven un 404.

Trata el 404 como un caso de caducidad o uso en tu controlador, tal como lo hace la ruta de verificación, y pide al usuario que solicite un nuevo código en lugar de volver a intentar el anterior. Si los usuarios se quedan sin tiempo habitualmente, acorta el proceso rellenando automáticamente el campo del código cuando el navegador admita el autocompletado de códigos SMS de un solo uso.

El SMS nunca llega o el envío es rechazado

El número no tiene el formato E.164 o es un tipo al que Twilio no puede acceder en tu cuenta. Verify espera un inicial y un código de país, como , y rechaza cualquier otra cosa con un 400.++14155552671

Valida el formato antes de llamar a Twilio, muestra el error de Twilio al usuario cuando falla un envío y envuelve los controladores de envío y verificación en Sentry error tracking on a Webflow Cloud app para que un pico de entregas fallidas aparezca con un seguimiento de pila en lugar de como una pérdida silenciosa.

Amplía la verificación por SMS en toda tu aplicación de Webflow Cloud

La configuración de esta guía te proporciona un segundo factor firmado y verificado por el servidor desde el edge. A partir de ahí, las extensiones naturales reutilizan los mismos controladores de ruta y el mismo patrón de sesión firmada.

La verificación de paso adicional es la siguiente implementación más común. En lugar de proteger solo el inicio de sesión, llama a los mismos controladores de inicio y verificación antes de una acción de alto riesgo, como un pago o un cambio de contraseña, y solicita un nuevo token firmado limitado a esa acción. El asistente de sesión firmada ya proporciona la base; solo tienes que acortar su duración y comprobarlo en la ruta sensible.

A partir de ahí, persistir el teléfono verificado de un usuario y su historial de verificación se combina de forma natural con la capa de datos detrás de una serverless database such as Neon on Webflow Cloud.

Explora Webflow + Twilio para ver cómo el SMS y la voz se conectan con el resto de tu sitio, desde un Code Embed en una página estática hasta el flujo de verificación basado en API de esta guía.