Webhooks

Cómo funciona

Con cada envío, formbase realiza un POST con un cuerpo JSON a tu URL de webhook. La solicitud está firmada con HMAC-SHA256, se reintenta en caso de fallo y se registra en el registro de eventos de la integración. Esta página cubre la configuración. El payload exacto, los encabezados y el algoritmo de firma están en la referencia de webhooks.

Añadir un webhook

1. 1

   Abre las integraciones del formulario

   Formulario → Configuración → Integraciones → Webhook.

2. 2

   URL

   Escribe el host y la ruta — el prefijo https:// es fijo en el campo. Solo se acepta http:// sin cifrar para localhost durante el desarrollo.

3. 3

   Mapeo

   Déjalo vacío para enviar todos los campos. Añade filas para enviar solo esos campos, bajo la clave JSON que elijas. El mapeo da forma a answers y display a la vez, así que una clave renombrada se renombra en ambos. La solicitud completa debajo del mapeo se redibuja a medida que la editas.

4. 4

   Encabezados

   Se genera automáticamente un secreto de firma que empieza con whsec_. No se puede cambiar tras la creación. En el mismo paso, añade hasta 5 encabezados personalizados que necesite tu endpoint, como un token de autorización, y activa Enviar la lista de campos con cada evento si tu receptor no puede llamar a fields.list. Content-Type se establece automáticamente y no se puede sobrescribir.

5. 5

   Finaliza

   Pulsa Enviar un evento de prueba para hacer POST de una respuesta de ejemplo sintetizada, y luego pulsa Crear integración.

Qué URLs acepta formbase

• https:// en todos los casos, o http:// para localhost y *.localhost durante el desarrollo.

• Sin credenciales en la URL, y como máximo 2.048 caracteres.

• Sin direcciones privadas o internas. El nombre de host se resuelve y se vuelve a comprobar justo antes de cada entrega, así que un registro DNS redirigido a una dirección interna después de la configuración sigue siendo rechazado.

Una URL rechazada es un problema de configuración, no algo transitorio: la entrega falla de forma permanente en lugar de reintentarse.

Qué recibes

Cada solicitud es el mismo sobre de evento — id, type, createdAt, apiVersion, test y data. Dentro de data están el formulario, el envío (id, correo del encuestado, hora de envío, enlace del PDF, idioma), un objeto answers indexado por clave de campo y un objeto display con las mismas claves como texto legible. Cada respuesta aparece una vez, en cada mapa.

Consulta la referencia para ver la forma completa del payload, answers y display, y cómo se representa un grupo repetible.

Para previsualizar el cuerpo exacto de tu formulario, abre la integración y despliega Payload de ejemplo debajo del secreto de firma. Muestra tu mapeo actual con respuestas de ejemplo.

Verificar firmas

Cada solicitud incluye un encabezado X-formbase-Signature: t=TIMESTAMP,sha256=HEX, un HMAC-SHA256 de TIMESTAMP.BODY calculado con tu secreto de firma. El secreto en sí nunca se envía. La referencia tiene un fragmento de verificación listo para copiar y pegar.

Eventos de respuestas abandonadas

Los webhooks personalizados solo se activan para envíos completados y ediciones — nunca para borradores abandonados. Un webhook personalizado es el único receptor que recibe ambos: una suscripción de Zapier, Make o n8n elige envíos nuevos o ediciones, nunca ambos. Para borradores abandonados, usa un proveedor que tenga un paso Envíos abandonados: Google Sheets, Airtable, Notion, Slack, Discord, Linear o GitHub Issues. Cada uno tiene su propia ventana de inactividad y, cuando aplica, su propia plantilla de mensaje. Ese paso requiere Pro o Business.

Reintentos y fallos

• Una entrega tiene éxito con cualquier 2xx.

• Hasta 5 intentos: el primero se lanza de inmediato, los reintentos esperan al menos 1, 2, 4 y 8 minutos. formbase busca reintentos pendientes cada 30 minutos, así que el último intento llega unas dos horas después del primero. Un encabezado Retry-After en un 429 o 5xx se respeta cuando pide una espera más larga.

• 429, 5xx, los tiempos de espera agotados y los fallos de conexión se reintentan. Cualquier otro 4xx falla de inmediato.

• Tras 5 fallos consecutivos, la integración se pausa automáticamente y la persona que la configuró recibe un correo. Soluciona el endpoint y luego pulsa Reanudar.

• 401, 403 y 404 detienen la integración de inmediato con un estado de error y el mismo correo — no hay que esperar a los cinco fallos.

• Las entregas que agotan los 5 intentos se acumulan en un banner de la integración. Reintentar todo vuelve a encolarlas y reactiva una integración pausada.

Pruebas

Enviar un evento de prueba aparece en el paso Finaliza y también en la integración guardada. Hace POST de una respuesta de ejemplo sintetizada — “John Doe” para texto, 42 para números, john@example.com para email — firmada y con tus encabezados personalizados, igual que una entrega real. Desde la integración guardada también escribe una entrada de prueba de conexión en el registro de eventos.

Para el desarrollo local, expón tu servidor de desarrollo con un túnel:

# ngrok
ngrok http 3000

# cloudflare tunnel

cloudflared tunnel --url http://localhost:3000

Preguntas frecuentes

Próximos pasos