Formstep

JSON firmado a tu propio endpoint

Cuando el destino es tu propio backend, una función serverless o una herramienta sin integración nativa, un webhook es la integración. Cada envío llega como un evento JSON, indexado por clave de campo, firmado para que puedas demostrar que viene de Formstep, y reintentado hasta que tu endpoint diga que sí.

Actualizado

Cómo funciona

  1. Abre las Integraciones del formulario, elige Webhook y escribe la URL. Deja la asignación vacía para enviar todos los campos, o añade filas para enviar solo algunos, con las claves JSON que elijas. Ver una solicitud de ejemplo muestra cómo cambia el cuerpo mientras editas.
  2. Copia el secreto de firma, que empieza por whsec_ y se muestra una sola vez. Añade hasta cinco cabeceras personalizadas, como un token de autorización.
  3. Haz clic en Activar Webhook y luego en Enviar un evento de prueba: un POST firmado con respuestas de ejemplo y tus cabeceras, registrado en el registro de eventos como una entrega real.

Ver la guía completa

Qué llega

Un solo sobre para todo lo que envía Formstep: id, type, createdAt, apiVersion, test y data. Dentro de data: el formulario, el envío con su id, el correo de quien respondió, la hora, el idioma y el enlace al PDF, un objeto answers para el código, indexado por clave de campo, y un objeto display con las mismas claves como texto legible. Una respuesta de opción es su clave de opción en answers y su etiqueta en display; un archivo es una lista con URL de descarga en uno y nombres de archivo en el otro. Un envío que respondió a una solicitud añade un bloque request con tu id externo y tus metadatos.

X-Formstep-Signature: t=TIMESTAMP,sha256=HEX

Un formulario puede tener varios webhooks; cada uno se dispara con cada envío y cada edición posterior, que se distinguen por type. Activa Enviar la lista de campos con cada evento si tu receptor no puede llamar a fields.list por sí mismo.

Reintentos

Cualquier 2xx es un éxito. Formstep lo intenta hasta cinco veces: de inmediato y luego tras al menos 1, 2, 4 y 8 minutos, así que el último intento llega unas dos horas después del primero. Se reintentan 429, 5xx, tiempos de espera agotados y fallos de conexión, y se respeta un Retry-After más largo. 401, 403 y 404 detienen la integración al instante y envían un correo a quien la configuró. Las entregas que agotaron los cinco intentos aparecen en un banner de la integración; Reintentar todo las envía de nuevo y reactiva una integración pausada.

Para el desarrollo local, expón tu servidor de desarrollo con ngrok o un túnel de Cloudflare y apunta el webhook a él. Para las respuestas de enlace público sin terminar, crea una suscripción submission_abandoned con la API REST; el webhook que añades aquí nunca se dispara para ellas.

Una herramienta de flujos de trabajo con un trigger de webhook, como Make o Pipedream, también puede recibirlos. Si el receptor es un flujo de trabajo que espera a una persona concreta, lo que quieres es el callback de una solicitud y no un webhook: se dispara una sola vez, para esa solicitud, con su resultado.

Preguntas sobre Formstep para Webhooks

¿Algo más en mente? La documentación cubre cada configuración, y respondemos los correos.

Un webhook pertenece al formulario y se dispara con cada envío, tanto de enlaces compartidos como de solicitudes. Un callback pertenece a una solicitud: la URL que pasas como callbackUrl al crearla, a la que se llama una vez cuando esa solicitud termina. Ambos llevan el mismo sobre de evento.

Cada petición tiene una cabecera X-Formstep-Signature con la forma t=TIMESTAMP,sha256=HEX: un HMAC-SHA256 de TIMESTAMP, un punto y el cuerpo sin procesar, con tu secreto de firma. Calcula el hash del cuerpo exactamente como llegó. La referencia de webhooks tiene un fragmento para copiar.

El propietario del espacio de trabajo puede verlo en el panel; los demás miembros ven el resto del webhook. No se puede regenerar: para un secreto nuevo, elimina el webhook y crea otro.

HTTPS en una dirección pública, de hasta 2048 caracteres, sin credenciales en la URL. El http:// simple funciona para localhost durante el desarrollo. Formstep comprueba el nombre de host otra vez antes de cada entrega, así que un registro DNS que más tarde apunte a una dirección interna sigue rechazándose.

Recopila información de cualquier persona.

Publica un formulario de ejemplo, respóndelo como lo haría tu destinatario y mira cómo llegan las respuestas. Sin necesidad de cuenta.

Lee la documentación