> Esta página documenta el contrato del payload y la API REST de suscripción. Para configurar un webhook personalizado para tu formulario > en la interfaz, consulta Webhooks personalizados. >
POST <your-url> con Content-Type: application/json.
Content-Type: application/json
X-Formstep-Signature: t={timestamp},sha256={hex} — presente cuando se configura un secreto de firma
(ver más abajo)
X-Formstep-Event-Id y X-Formstep-Event-Type — los mismos valores que id y type en el
cuerpo, para que puedas deduplicar y enrutar antes de analizar. Un callback de solicitud envía las
mismas dos.
Content-Type, que no se
puede sobrescribir. Las suscripciones nativas creadas mediante webhooks.create no tienen cabeceras personalizadas.
Cuando configuras una integración de webhook, eliges qué evento activa las entregas:
Los tres eventos request_* se suscriben mediante webhooks.create y son lo que escuchan las apps de Formstep para
Zapier, Make y n8n. Cada uno entrega el mismo envoltorio que envía un callback de solicitud, firmado
con el secreto propio de la suscripción. Las solicitudes de prueba nunca llegan a una suscripción, y requests.replayCallback{' '}
reenvía solo el callback. Una suscripción, un evento: submission_created es tráfico de enlace público y{' '}
request_completed es tráfico de solicitudes, así que una solicitud completada nunca dispara submission_created,
y un formulario con ambas suscripciones recibe una sola entrega por finalización. Una edición solo llega a una suscripción{' '}
submission_updated, nunca a una submission_created. El webhook que configuras en Configuración del formulario no
tiene elección de evento: recibe por igual las primeras respuestas y las ediciones, distinguidas por type.
El campo type en el cuerpo JSON indica qué ocurrió:
submission.completed — una nueva respuesta completada
submission.updated — una respuesta existente fue editada
submission.abandoned — un borrador fue abandonado tras el periodo de inactividad configurado
Un callback de solicitud y una suscripción request_* usan el mismo envoltorio con{' '}
request.completed, request.expired y request.canceled, así que un solo analizador lee los seis.
answers es el objeto plano {'{ field key: value }'}, indexado por las claves de campo fijadas al publicar.
Consúltalo cuando un flujo de trabajo ramifique o almacene un valor: answers.email, sin array que recorrer. Una respuesta de
elección es la clave de la opción elegida — el key que fields.list indica para esa opción — así
que es el mismo sea cual sea el idioma en que respondió el respondente. Una fecha es una cadena ISO, un número es un número, una selección
múltiple es un array de claves de opción. Los campos sin responder se omiten, nunca se envían como null.
display lleva las mismas claves con texto legible por humanos: la etiqueta de la opción en lugar de su clave, una fecha con
formato, una lista unida. Consúltalo cuando una persona vaya a ver el valor — un mensaje de Slack, una celda de hoja de cálculo, un
correo.
Un grupo repetitivo aparece en answers una vez, bajo la propia clave de campo del grupo, como un array de objetos de fila
indexados por la clave de campo de cada miembro — answers.attendees[0].attendee_name arriba — y en display como
una sola línea con las filas unidas. Un miembro nunca se eleva al nivel superior.{' '}
Los campos calculados aparecen en ambos mapas bajo el nombre del campo calculado como
su clave (answers.total).
Una pregunta de Programar cita y un campo de Pago llevan cada uno un objeto en answers, bajo la clave de campo de la
pregunta, y una línea de texto en display. Las horas son instantes ISO, así que una hoja de cálculo o un flujo de trabajo
puede interpretarlas sea cual sea el idioma en que respondió el respondente:
El status de una reserva es confirmed, rescheduled, cancelled, rejected o{' '}
no_show. El de un pago es paid, partially_refunded, refunded o disputed,
y amount está en la unidad principal de la moneda: 40 son $40.00. Cuando Cal.com mueve una reserva o Stripe
reembolsa un pago después del envío, Formstep actualiza el objeto, así que submissions.list y los eventos posteriores
muestran el estado actual; no se envía ningún evento nuevo por el cambio.
Antes de apiVersion 2026-09-24, una reserva se enviaba como una sola frase en answers y un pago no
se enviaba en absoluto.
El mapeo de campos del webhook se aplica a ambos mapas a la vez: elige campos "seleccionados" y los demás se omiten; renombra la columna
de un campo y el nuevo nombre es su clave tanto en answers como en display. Un campo que el formulario publicó
antes de que existieran las claves de campo sale bajo su id de elemento; vuelve a publicar el formulario para darle una clave legible.
El evento no repite el título ni el tipo de cada campo. Léelos desde fields.list, que es estable por{' '}
data.form.snapshotId, así que puedes cachear la lista de campos y volver a pedirla solo cuando cambie el id del snapshot. Un
receptor que no puede hacer una segunda llamada puede activar Enviar la lista de campos con cada evento en la
configuración del webhook; el evento entonces lleva data.schema, una entrada por campo. Una pregunta de elección lista sus{' '}
options y una matriz sus rows y columns, cada una como {'{ key, label }'}, así que las
claves en answers se resuelven en etiquetas sin una segunda llamada:
En el webhook personalizado configurado en la configuración del formulario, un envío que respondió
a una solicitud lleva un objeto extra dentro de data, request. Está ausente
en todo envío de enlace público, así que su presencia es la forma en que ese receptor distingue los dos canales. Una suscripción de
Zapier, Make o n8n nunca lo ve: el tráfico de solicitudes llega a una suscripción como request.completed, que lleva el bloque
request completo.
id — la solicitud que respondió este envío. Pásala a requests.get para ver el panorama completo.
externalId y metadata — tu propia contabilidad, tal como la diste en requests.create. Cada una
solo está presente si se estableció.
> Un webhook de envío se dispara en un envío; el bloque request solo nombra la solicitud que respondió. Un{' '}
> callback se dispara cuando una solicitud termina — completada, expirada o cancelada — y lleva{' '}
> context y outcome. La expiración y la cancelación no tienen envío, así que nunca se dispara un webhook de
> envío para ellas. Para escuchar el fin de una solicitud sin una URL de callback, suscríbete a request_completed,{' '}
> request_expired o request_canceled mediante webhooks.create.
>
data.submission.pdfUrl es un enlace al PDF de la respuesta. Un formulario con un webhook personalizado o una suscripción de
Zapier, Make o n8n conserva un PDF de cada respuesta, así que sus eventos incluyen el enlace. Solo es null cuando la
respuesta no tiene PDF.
data.submission.language es el código BCP-47 del idioma en que el respondente envió el formulario (para formularios
traducidos). Es null para formularios de un único idioma. Úsalo para enrutar o ramificar según el idioma del respondente sin
necesidad de una consulta adicional.
Cuando te suscribes a submission_abandoned, Formstep comprueba borradores inactivos cada hora. Si un borrador ha estado
inactivo más allá del período de inactividad configurado, Formstep realiza una entrega.
Las integraciones nativas de la API deben enviar idleWindow a webhooks.create. Los valores aceptados son{' '}
12h, 1d, 3d y 1w. No hay un valor predeterminado implícito; una suscripción a abandono
sin valor se rechaza.
La estructura del payload es idéntica a la de una respuesta completada. Hay dos diferencias:
answers y display las preguntas que el
respondente respondió.
submittedAt
{' '}
— usa la marca de tiempo de envío como alternativa, ya que el respondente nunca envió formalmente la respuesta.
Cada integración se activa como máximo una vez por borrador abandonado. Tras la entrega, el borrador queda excluido de futuros ciclos de comprobación.
Cada webhook tiene su propio secreto de firma — se establece en la interfaz cuando configuras un webhook personalizado, o con el parámetro
opcional signingSecret (32–255 caracteres) en webhooks.create. No es el secreto de firma de solicitudes del
espacio de trabajo usado para los callbacks de solicitud, pero la cabecera y el algoritmo son
idénticos, así que un solo verificador se encarga de ambos.
Toda entrega firmada lleva X-Formstep-Signature: t={seconds},sha256={hex}. El digest es un HMAC-SHA256 de{' '}
{t}.{raw body}, con tu secreto como clave. Dos reglas: calcula el hash del cuerpo{' '}
sin procesar antes de cualquier análisis o reserialización, y compara en tiempo constante.
Formstep no impone una ventana contra repetición, así que la tolerancia anterior la eliges tú. Cambiar el secreto tiene efecto en el siguiente intento, incluidos los reintentos ya en curso — actualiza primero tu receptor.
> ⚠️ **Verifica siempre en producción** >Sin verificación, cualquiera que descubra tu URL puede enviar respuestas falsas.
Formstep realiza hasta 5 intentos por entrega — 1 inicial y 4 reintentos — con al menos 1, 2, 4 y 8 minutos de diferencia entre sí.
Formstep busca reintentos pendientes cada 30 minutos, así que un reintento puede llegar hasta media hora después de que termina su
retroceso, y el último intento unas dos horas después del primero. Se respeta una cabecera Retry-After en tu respuesta cuando
pide más tiempo que el siguiente paso de retroceso. Una entrega se considera fallida si tu endpoint:
Un caso nunca se reintenta: un destino bloqueado, no resoluble, o que resuelve a una dirección privada. La URL se revalida — DNS incluido — justo antes de cada intento, así que un host que deja de estar permitido falla la entrega de inmediato en lugar de gastar el presupuesto de reintentos.
Tras 5 entregas consecutivas fallidas, la integración se pausa. Soluciona el endpoint y vuelve a habilitarla desde Configuración del formulario → Integraciones; una entrega exitosa reinicia el contador.
Los reintentos de entrega del mismo evento reutilizan el mismo id, así que deduplica almacenando los ids procesados. Un
evento genuinamente nuevo — por ejemplo, cuando una persona edita su envío — llega con un id nuevo y{' '}
type: "submission.updated": en el webhook de Configuración del formulario, o en una suscripción{' '}
submission_updated. El createdAt es el momento en que se puso en cola el evento, no el del intento, así que se
mantiene igual también entre reintentos. Para distinguir las ediciones, lee data.submission.editCount: aumenta con cada
edición, y data.submission.updatedAt indica cuándo ocurrió la última.
Tanto el panel de configuración como el panel de detalle de la integración tienen un botón Enviar prueba. Envía una
muestra del evento suscrito a tu URL para que puedas verificar la conexión sin esperar a una respuesta o solicitud real. Las mismas
muestras están disponibles a través de la API como submissions.sample y requests.sample.
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 ``` > 💡 **Desarrollo local** >Usa la URL del túnel como tu endpoint de webhook y luego haz clic en Enviar prueba para verificar de extremo a extremo.