Back

Documentation

How to embed surveys on your site and receive responses via webhook.

How to embed the widget

Paste the snippet below before </body> on any HTML page. Replace SEU_EMBED_CODE with your survey code — visible in the Share tab inside the dashboard.

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

The script loads asynchronously (does not block the page) and automatically applies the targeting rules configured in the survey — URL, scroll, time on page or exit intent.

Prerequisites

The survey must have status Active (published). Surveys in draft do not display the widget.

Identify the visitor (email / userId)

Use window.PulseForm.identify({ email, userId }) to associate the response with a known user (your app login, CRM customer, etc). The identity is persisted in localStorage (key sb_identity_{embed_code}) and sent along with the response in the field metadata.identity.

Works in both the embeddable widget and the public link of the form.

Basic usage

<script>
  // After the user logs into your app
  window.PulseForm.identify({
    email: 'cliente@empresa.com',
    userId: '12345'
  });
</script>

Can be called before or after the widget script loads — earlier calls are queued and processed at initialization.

Additional traits

Accepts any scalar key/value (string, number, boolean) — useful for segmentation.

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

Public link with query string

For email campaigns, just pass via URL:

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

The form automatically reads email and userId from the query and populates the identity.

Full API

• identify(traits) — merges traits into the persisted profile. Max 50 keys, 500 chars/value, 4 KB total.
• reset() — clears identity (use on your app logout).
• getIdentity() — returns a copy of the current profile or null.

Where it appears

Each response submitted includes the profile in metadata.identity, visible in the Responses tab of the survey and in the webhook payload.

How to connect a webhook

The webhook triggers a POST to the URL you configure on each new response received. Useful for integrating with Zapier, Make, n8n or any internal system.

Payload

Body sent on each trigger (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
    }
  }
}

Authentication and retry

In addition to the payload, each request includes two fixed headers:

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

On failure (timeout or HTTP status ≥ 400), the system retries 2 more times with exponential backoff. If all 3 attempts fail, the error is logged but the visitor's response is not lost — it was already saved to the database before triggering.