Volver

Documentación

Cómo embeber surveys en tu sitio y recibir respuestas vía webhook.

Cómo embeber el widget

Pega el snippet de abajo antes de </body> en cualquier página HTML. Reemplaza SEU_EMBED_CODE por el código de tu survey — visible en la pestaña Compartir dentro del panel.

<script async src="https://surveybuilder-production-34c0.up.railway.app/widget.min.js"
  data-survey-code="SEU_EMBED_CODE">
</script>

El script carga de forma asíncrona (no bloquea la página) y aplica automáticamente las reglas de targeting configuradas en el survey — URL, scroll, tiempo en página o intención de salida.

Prerrequisitos

El survey debe estar con estado Activo (publicado). Los surveys en borrador no muestran el widget.

Identificar al visitante (email / userId)

Usa window.PulseForm.identify({ email, userId }) para asociar la respuesta a un usuario conocido (login de tu app, cliente CRM, etc). La identidad se persiste en localStorage (clave sb_identity_{embed_code}) y se envía junto con la respuesta en el campo metadata.identity.

Funciona tanto en el widget embebible como en el enlace público del formulario.

Uso básico

<script>
  // Tras el inicio de sesión del usuario en tu app
  window.PulseForm.identify({
    email: 'cliente@empresa.com',
    userId: '12345'
  });
</script>

Se puede llamar antes o después de que cargue el script del widget — las llamadas anteriores se ponen en cola y se procesan en la inicialización.

Traits adicionales

Acepta cualquier clave/valor escalar (string, número, boolean) — útil para segmentación.

window.PulseForm.identify({
  email: 'cliente@empresa.com',
  userId: '12345',
  plan: 'pro',
  company: 'Acme',
  signupDate: '2024-08-12'
});

Enlace público con query string

Para campañas por correo, basta con pasarlo vía URL:

https://seu-dominio.com/survey/EMBED_CODE?email=cliente@empresa.com&userId=12345

El formulario lee automáticamente email y userId de la query y popula la identidad.

API completa

• identify(traits) — combina traits al perfil persistido. Máx. 50 claves, 500 chars/valor, 4 KB total.
• reset() — limpia la identidad (úsalo en el logout de tu app).
• getIdentity() — retorna copia del perfil actual o null.

Dónde aparece

Cada respuesta enviada incluye el perfil en metadata.identity, visible en la pestaña Respuestas del survey y en el payload del webhook.

Cómo conectar un webhook

El webhook dispara un POST a la URL que configures con cada nueva respuesta recibida. Útil para integrar con Zapier, Make, n8n o cualquier sistema interno.

Payload

Cuerpo enviado en cada disparo (Content-Type: application/json):

{
  "event": "response.submitted",
  "survey_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "timestamp": "2025-05-04T14:32:00.000Z",
  "data": {
    "session_id": "uuid-da-sessao",
    "page_url": "https://meusite.com/pricing",
    "answers": {
      "q1": "opcao_a",
      "q2": "texto livre",
      "q3": 9
    }
  }
}

Autenticación y retry

Además del payload, cada request incluye dos headers fijos:

X-PulseForm-Token: {token}
X-PulseForm-Event: response.submitted
X-PulseForm-Attempt: 1

En caso de fallo (timeout o estado HTTP ≥ 400), el sistema reintenta 2 veces más con backoff exponencial. Si los 3 intentos fallan, el error se registra pero la respuesta del visitante no se pierde — ya fue guardada en la base antes del disparo.