Configura la verificación alojada con una bandeja de prueba

Al final de este tutorial tendrás un formulario de contacto que funciona cuyos envíos verifica Caputchin y se entregan a un webhook, y habrás visto un envío verificado aterrizar en una bandeja de prueba que puedes inspeccionar. Usamos webhook.site como destino primero, porque te muestra el payload exacto que Caputchin envía antes de que te comprometas con tu propio endpoint.

Necesitas un plan Alpha, Equipo o Apex (la verificación alojada no está en Solo), una clave de sitio, y una página donde puedas editar el HTML del formulario. Si todavía no has añadido el widget a una página, añade el widget primero; este tutorial asume un <caputchin-widget> que funciona.

1. Consigue una bandeja de prueba

Abre webhook.site en una pestaña nueva. Te da de inmediato una URL única con la pinta de https://webhook.site/#!/<uuid>, y una URL de entrega a juego de la forma https://webhook.site/<uuid>. Copia la URL de entrega (la que no tiene el #!/). Deja la pestaña abierta; cada petición que recibe aparece ahí en tiempo real.

Esta URL es un sustituto de tu webhook real. Trátala como desechable, ya que cualquiera con la URL puede leer lo que llega.

2. Activa la verificación alojada

En el dashboard, abre la clave de sitio y ve a su página de Verificación alojada.

Pega la URL de entrega de webhook.site en el campo webhook URL.
Deja email vacío por ahora.
Guarda.

No tienes que mover el interruptor enabled todavía. El siguiente paso usa Test delivery, que funciona sobre un destino guardado esté o no encendida la verificación alojada, así que puedes confirmar el cableado antes de salir a producción.

3. Envía una entrega de prueba

En la misma página, usa Test delivery. Caputchin envía un envío sintético directo a tu destino sin correr un juego ni verificar un token, así que es una comprobación pura del cableado del destino.

Cambia a la pestaña de webhook.site. Un nuevo POST aparece en un segundo o dos. Su cuerpo JSON tiene esta pinta:

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "test_...",
    "game_id": null,
    "score": null,
    "duration_ms": null,
    "verified_at": 1748640000000,
    "test": true
  },
  "form": {
    "email": "test@example.com",
    "message": "Test submission from your Caputchin dashboard."
  }
}

El marcador "test": true le dice a tu handler que esto fue una prueba del dashboard, no un visitante real; está ausente en los envíos reales. Si ves este payload, el destino funciona. Si no llega nada, revisa que copiaste la URL de entrega (no la URL de visor #!/) y la guardaste.

4. Apunta tu formulario al reenviador

Ahora haz que un envío real pase por Caputchin. El único cambio en tu formulario es su action: en vez de tu propio backend, postea a la URL del reenviador que la clave de sitio te muestra en la página de Verificación alojada.

<form action="https://caputchin.com/api/forward/cpt_pub_..." method="POST">
  <input name="email" type="email" />
  <input name="message" />
  <caputchin-widget sitekey="cpt_pub_..."></caputchin-widget>
  <button type="submit">Send</button>
</form>

Nada más cambia. El widget sigue inyectando el campo oculto caputchin-token cuando el visitante supera el reto; el reenviador lee ese campo, lo verifica, y lo elimina antes de entregar el resto a tu destino.

5. Activa la verificación alojada

De vuelta en la página de Verificación alojada, mueve el interruptor enabled a encendido y guarda. El reenviador rechaza envíos para una clave de sitio que no está activada, así que este interruptor es lo que pone en producción el paso 4.

6. Envía el formulario de verdad

Carga tu página, rellena el formulario, supera el reto, y envía. Mira la pestaña de webhook.site: llega un segundo POST, esta vez sin campo test y con metadato de verificación real.

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "...",
    "game_id": "caputchin/games/leaf-memory",
    "score": 847,
    "duration_ms": 4200,
    "verified_at": 1748640000000
  },
  "form": {
    "email": "visitor@example.com",
    "message": "Hello!"
  }
}

Ese es el camino entero: el visitante envía, Caputchin verifica, tu destino recibe solo el envío verificado. Un envío que falla la verificación (un token ausente, expirado o reusado) nunca llega a tu destino en absoluto.

Trata el bloque caputchin como tratarías un veredicto de backend: game_id, score y duration_ms son metadato declarado por el cliente para tu analítica, no una señal de confianza. La decisión de confianza es el hecho de que el envío llegara siquiera. Cualquiera de esos tres puede ser null en un envío real (por ejemplo una verificación sin juego), así que protege contra null antes de leerlos.

7. Prueba también el destino de correo

webhook.site también da a cada bandeja una dirección de correo, así que puedes probar la entrega por correo de la misma forma. En la página de webhook.site, encuentra la dirección de correo única de tu bandeja y cópiala; al momento de escribir esto tiene la pinta de <your-inbox-id>@emailhook.site, pero revisa la página para la forma actual ya que webhook.site es dueño de ese detalle. Luego:

De vuelta en la página de Verificación alojada, pega esa dirección en el campo email.
Guarda, y usa Test delivery otra vez.

El correo llega a la bandeja de webhook.site junto a las peticiones: un mensaje plano que lleva los campos del formulario y un pie que indica que Caputchin verificó el envío. El correo se entrega a través del proveedor de correo de Caputchin, así que puede tardar un poco más en aterrizar que un POST de webhook. Con una URL de webhook y una dirección de correo fijadas a la vez, un solo envío reparte a ambos, y cuenta como entregado si cualquiera de los dos tiene éxito.

8. Cambia a tu destino real

Cuando la bandeja de prueba te haya mostrado qué esperar, reemplázala por el tuyo:

Tu propio webhook. Pon la URL de tu endpoint en el campo webhook URL. Debe ser una URL https pública; Caputchin rechaza URLs que resuelven a direcciones privadas, de loopback o de metadatos de nube, y no seguirá redirects. Tu handler recibe exactamente la forma JSON de arriba. Las entregas no van firmadas, así que mantén la URL secreta, ya que su secreto es lo que autentica la llamada.
Correo en su lugar, o además. Pon tu propia dirección en el campo email, igual que la probaste arriba. Puedes correr ambos a la vez, por ejemplo un webhook para procesar más una copia por correo a ti mismo.

Envía un envío real más contra el destino en producción para confirmar, y entonces habrás terminado.

A dónde ir después

Estadísticas de verificación alojada: vigila la salud de entrega en el tiempo.
Verificación alojada: los conceptos, la postura de privacidad, y qué se deja fuera a propósito.
Verifica en tu backend: la alternativa si más tarde añades un servidor.

Configura la verificación alojada con una bandeja de prueba

En esta página