Con cada envío, Formstep 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.
Puedes asociar varios webhooks a un mismo formulario. Cada uno se activa de forma independiente para cada evento.
https:// en todos los casos, o http:// para localhost y *.localhost durante el
desarrollo.
Una URL rechazada es un problema de configuración, no algo transitorio: la entrega falla de forma permanente en lugar de reintentarse.
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.
Cada solicitud incluye un encabezado X-Formstep-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.
> Sin verificación, cualquiera que descubra tu URL puede enviar envíos falsos. Rechaza las solicitudes en las que la firma falte o sea > inválida. >
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.
2xx.
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.
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.
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 ```Sí. Cada uno tiene su propia URL, secreto de firma y cabeceras personalizadas. Todos los webhooks activos se activan de forma independiente para cada envío.
Sí — hasta 5, añadidas durante la configuración o después desde la integración. Content-Type se establece automáticamente y
cualquier intento de sobrescribirlo se ignora.
No. El secreto de firma se genera una sola vez al crear el webhook y no se puede cambiar. Si necesitas un nuevo secreto, elimina el webhook y crea uno nuevo.
Sí. Abre la integración, edita la URL y guarda. El secreto de firma y el historial de eventos se mantienen.
Solo para localhost y *.localhost durante el desarrollo. El resto de URLs deben usar HTTPS.
Elimínala desde Configuración del formulario → Integraciones. Formstep deja de enviar solicitudes de inmediato, y el historial de eventos de la integración se elimina con ella.