Voltar

Documentação

Como imbutir surveys no seu site e receber respostas via webhook.

Como imbutir o widget

Cole o snippet abaixo antes do </body> de qualquer página HTML. Troque SEU_EMBED_CODE pelo código do seu survey — visível na aba Compartilhar dentro do painel.

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

O script carrega de forma assíncrona (não bloqueia a página) e aplica automaticamente as regras de targeting configuradas no survey — URL, scroll, tempo na página ou intenção de saída.

Pré-requisitos

O survey precisa estar com status Ativo (publicado). Surveys em rascunho não exibem o widget.

Identificar o visitante (email / userId)

Use window.PulseForm.identify({ email, userId }) para associar a resposta a um usuário conhecido (login do seu app, cliente CRM, etc). A identidade é persistida em localStorage (chave sb_identity_{embed_code}) e enviada junto da resposta no campo metadata.identity.

Funciona tanto no widget embedável quanto no link público do formulário.

Uso básico

<script>
  // Após o usuário logar no seu app
  window.PulseForm.identify({
    email: 'cliente@empresa.com',
    userId: '12345'
  });
</script>

Pode ser chamado antes ou depois do script do widget carregar — chamadas anteriores ficam em fila e são processadas na inicialização.

Traits adicionais

Aceita qualquer chave/valor escalar (string, número, boolean) — útil para segmentação.

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

Link público com query string

Para campanhas por e-mail, basta passar via URL:

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

O formulário lê automaticamente email e userId da query e popula a identidade.

API completa

• identify(traits) — mescla traits ao perfil persistido. Máx. 50 chaves, 500 chars/valor, 4 KB total.
• reset() — limpa identidade (use no logout do seu app).
• getIdentity() — retorna cópia do perfil atual ou null.

Onde aparece

Cada resposta enviada inclui o perfil em metadata.identity, visível na aba Respostas do survey e no payload do webhook.

Como conectar um webhook

O webhook dispara um POST para a URL que você configurar a cada nova resposta recebida. Útil para integrar com Zapier, Make, n8n ou qualquer sistema interno.

Payload

Corpo enviado a 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
    }
  }
}

Autenticação e retry

Além do payload, cada requisição inclui dois headers fixos:

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

Em caso de falha (timeout ou status HTTP ≥ 400), o sistema tenta mais 2 vezes com backoff exponencial. Se as 3 tentativas falharem, o erro é registrado no log mas a resposta do visitante não é perdida — ela já foi salva no banco antes do disparo.