Webhooks

Envíe cada respuesta a una dirección propia, en JSON, en el momento en que llega.

Un POST por respuesta

Se envía en cuanto la respuesta queda guardada, sin hacer esperar a quien la ha enviado.

Una estructura JSON estable

Nombres de tipo públicos e ID de campo permanentes, así que renombrar una pregunta nunca rompe su código.

10 segundos, un intento

Fillio espera diez segundos a su endpoint y después no vuelve a intentarlo.

Activar un webhook

Abra el formulario, vaya a la pestaña Configuración y active Webhook. Pegue la dirección que debe recibir los envíos; Fillio la guarda poco después de que deje de escribir y lo confirma en pantalla. Cada formulario lleva una sola dirección, y volver a desactivar el interruptor la borra.

La dirección tiene que ser HTTPS

Fillio solo llama a direcciones que empiezan por https://. El campo de configuración acepta una dirección http:// pero nunca la llama, así que un webhook que parece guardado no entregará nada, en silencio.

También se rechazan las direcciones que apuntan al interior de una red privada: cualquier host en 10.x, 127.x, 169.254.x, 172.16-31.x o 192.168.x, cualquier dirección IPv6 y cualquier nombre que sea localhost o termine en .local o .internal. Su endpoint tiene que ser accesible desde la internet pública.

La petición

Un POST con un cuerpo JSON. Lo acompañan cuatro cabeceras.

Cabecera	Descripción
Content-Type: application/json	El cuerpo siempre es JSON.
User-Agent: Fillio Webhooks/1.0	Identifica a quien llama como Fillio, algo útil cuando un mismo endpoint escucha a varios servicios.
X-Fillio-Event: FORM_RESPONSE	El nombre del evento. FORM_RESPONSE es el único valor que Fillio envía hoy.
X-Fillio-Event-Id	Un UUID nuevo para esta entrega, repetido como eventId en el cuerpo.

El payload

Un sobre que describe el evento y un objeto data que describe la respuesta.

{
  "eventId": "8f2c1d7a-4b09-4e5c-9a13-6d0f8b2e77c4",
  "eventType": "FORM_RESPONSE",
  "createdAt": "2026-08-26T09:14:22.481Z",
  "data": {
    "responseId": "Qh3Rk9wZm1sVtY7cN2xP",
    "formId": "7bTn4Kq2Wx",
    "formName": "Workshop signup",
    "createdAt": "2026-08-26T09:14:22.481Z",
    "fields": [
      {
        "key": "V1StGXR8_Z5jdHi6B-myT",
        "label": "Full name",
        "type": "INPUT_TEXT",
        "value": "Mira Kaya"
      },
      {
        "key": "kM4pQz7LxAe2Rn0BsTvUw",
        "label": "Which session?",
        "type": "MULTIPLE_CHOICE",
        "value": "c9XbNf3JdQ",
        "options": [
          { "id": "c9XbNf3JdQ", "text": "Morning" },
          { "id": "eR2mYt8KpL", "text": "Afternoon" }
        ]
      },
      {
        "key": "zA6cWn1FyH4tXd9QrLbEs",
        "label": "How likely are you to recommend us?",
        "type": "LINEAR_SCALE",
        "value": 9
      }
    ]
  }
}

Propiedad	Descripción
eventId	Un ID único para esta entrega.
eventType	Siempre FORM_RESPONSE.
createdAt	Cuándo se envió la respuesta, como marca de tiempo ISO 8601 en UTC.
data.responseId	El ID de la respuesta guardada.
data.formId	El ID del formulario, el mismo que aparece en su enlace público.
data.formName	El título del formulario como texto plano, sin ningún formato.
data.fields	Una entrada por cada pregunta contestada.

Dentro de fields

Cada entrada lleva cuatro propiedades, y una pregunta con opciones lleva una quinta.

Propiedad	Descripción
key	El ID permanente de la pregunta. Sobrevive a cualquier cambio en el enunciado, así que haga la correspondencia por este valor y no por la etiqueta.
label	La pregunta tal como está escrita en el editor.
type	El tipo de pregunta, tomado de la lista de abajo.
value	La respuesta, con la forma en que esa pregunta la guarda.
options	Solo en preguntas con opciones: el ID y el texto de cada opción, para que pueda convertir una respuesta de vuelta en una etiqueta.

Solo llegan las preguntas contestadas

Una pregunta que la persona no tocó no aparece en el array, en lugar de enviarse con un valor vacío, y una pregunta oculta por la lógica condicional no aparece nunca. Busque cada respuesta por su key en lugar de fiarse de la posición o de un número fijo de entradas.

Las respuestas de opción llevan ID, no etiquetas

La respuesta de un desplegable o de una opción múltiple es el ID de la opción elegida, y la de casillas, selección múltiple o clasificación es un array de ID de opción. Resuélvalos con la lista options de la misma entrada. Una respuesta de clasificación conserva el orden en que la persona colocó los elementos.

La opción Otro

Cuando alguien escribe en una casilla Otro, el valor no es un ID de opción sino el texto __OTHER__: seguido de lo que haya escrito. Quite ese prefijo para leer la respuesta.

"value": "__OTHER__:Heard about it from a friend"

Archivos y firmas

La respuesta de una subida de archivo es un enlace de descarga al archivo en el almacenamiento de Fillio. La respuesta de una firma es una data URL PNG en base64, que puede guardar o mostrar directamente.

Tipos de campo

El tipo es un nombre público estable, así que un cambio interno en Fillio nunca llega a su integración. Todo lo que Fillio no pueda mapear llega como INPUT_TEXT.

Tipo	Pregunta	Valor
INPUT_TEXT	Respuesta corta	Texto
TEXTAREA	Respuesta larga	Texto
INPUT_EMAIL	Correo electrónico	Texto
INPUT_PHONE_NUMBER	Número de teléfono	Texto
INPUT_NUMBER	Número	El número como texto, exactamente como se escribió
INPUT_LINK	Enlace	Texto
INPUT_DATE	Fecha	Una fecha, como YYYY-MM-DD
INPUT_TIME	Hora	Una hora, como HH:MM en formato de 24 horas
DROPDOWN	Desplegable	Un ID de opción
MULTIPLE_CHOICE	Botones de opción	Un ID de opción
CHECKBOXES	Casilla de verificación	Un array de ID de opción
MULTI_SELECT	Selección múltiple	Un array de ID de opción
RATING	Valoración con estrellas	Un número
LINEAR_SCALE	Escala lineal	Un número
RANKING	Clasificación	Un array de ID de opción, en el orden de quien responde
FILE_UPLOAD	Subir archivo	Un enlace de descarga
SIGNATURE	Firma	Una data URL PNG en base64

Si su endpoint no responde

Fillio espera diez segundos. Un tiempo de espera agotado, un error de conexión o cualquier estado fuera del rango 2xx cuenta como entrega fallida, y ahí acaba todo: no hay reintento ni cola desde la que reproducirla.

La respuesta en sí nunca se ve afectada. Se guarda antes de hacer la petición y permanece en su panel haga lo que haga su endpoint, así que el panel sigue siendo el registro completo aunque se pierda una entrega.

No hay firma

Fillio no firma la petición ni envía ningún secreto compartido, así que el cuerpo por sí solo no demuestra de dónde viene. Si su endpoint necesita estar seguro, dele una dirección que solo usted conozca: una ruta o cadena de consulta larga e imposible de adivinar. Y trate como no fiable cualquier cosa que llegue a otro sitio.

Cada entrega lleva su propio ID de evento, tanto en la cabecera X-Fillio-Event-Id como en el cuerpo. Registrar los que ya ha procesado es la forma más sencilla de que su endpoint pueda recibir dos llamadas sin problema.

Consejo

Apunte el webhook a cualquier endpoint de inspección de peticiones y envíe su propio formulario una vez. Verá el payload exacto que produce, con sus propios ID de campo dentro: la forma más rápida de escribir la correspondencia en su lado.