Integration API Setup

What is this for?

This guide explains how to connect your form to an external system (like a CRM, marketing platform, or custom webhook) so that every time someone submits the form, the data is automatically sent to your specified URL.

Setting Up the Integration

In the Form Constructor, open the Integration Setup (optional) step. You will see one field:

Integration API URL
Enter the full web address (URL) of the endpoint that should receive the form submission data. The URL must start with http:// or https://.

Requirements and limits:

Maximum 500 characters.
Must be a valid, publicly reachable URL.
Localhost and private IP addresses (e.g., 127.0.0.1, 169.254.169.254) are blocked for security.
The request will time out after 5 seconds if your endpoint does not respond.

How to configure it:

Open your form in the Form Constructor.
Click the Integration Setup (optional) step in the sidebar.
Paste your webhook URL into the Integration API URL field.
Click Save (or just move to another step — changes are auto-saved).

Note: The small “show info about integration” link next to the field currently does not display additional help. This is a known limitation and will be improved in a future update.

What Happens When a Form Is Submitted

Once the Integration URL is saved and the form is activated, every submission triggers a POST request from our server to your URL. The request body is a JSON object with the following structure:

JSON Payload Example

{
  "event": "form_submission",
  "form_id": "evt_abc123def456",
  "submitted_at": "2026-07-19T14:32:10.123Z",
  "answers": {
    "email_abc123": "john.doe@example.com",
    "first_name_def456": "John",
    "last_name_ghi789": "Doe",
    "company_jkl012": "Acme Corp",
    "newsletter_opt_in_mno345": true,
    "interests_pqr678": "Marketing, Sales"
  },
  "data": {
    "fields": [
      { "id": "abc123", "label": "Email", "code": "email", "value": "john.doe@example.com" },
      { "id": "def456", "label": "First Name", "code": "first_name", "value": "John" },
      { "id": "ghi789", "label": "Last Name", "code": "last_name", "value": "Doe" },
      { "id": "jkl012", "label": "Company", "code": "company", "value": "Acme Corp" },
      { "id": "mno345", "label": "Subscribe to newsletter", "code": "newsletter_opt_in", "value": true },
      { "id": "pqr678", "label": "Interests", "code": "interests", "value": [{ "name": "Marketing" }, { "name": "Sales" }] }
    ]
  }
}

Field Explanations

Field	Type	Description
`event`	string	Always `"form_submission"`. Identifies the event type.
`form_id`	string	The unique ID of the form/event that was submitted.
`submitted_at`	string (ISO 8601)	Exact date and time of the submission in UTC.
`answers`	object	A flat key–value map of all form answers. Keys follow the pattern `<field_code>_<field_id>` (e.g., `email_abc123`). Values are processed for easy reading: text/number fields become strings; checkboxes become `true`/`false`; dropdowns and multi-selects become a comma-separated list of the selected option names.
`data.fields`	array	The original array of form fields exactly as stored in the submission, including raw values (objects for selects, arrays for multi-selects, etc.). Use this if you need the full structure.

How Answers Are Flattened (`answers` object)

The answers object is designed for easy parsing in webhooks, Zapier, Make, or custom code:

Text, Number, Email, Phone, URL, Textarea → string value.
Checkbox / Toggle → true or false.
Select (single) → the selected option’s name as a string.
Multi-select / Checkbox group → comma-separated list of selected option name values (e.g., "Marketing, Sales").
Hidden / System fields → included if present.

Technical Details (For Your Developer)

If you are forwarding this to a developer who will build the receiving endpoint, share these details:

Method: POST
Content-Type: application/json
User-Agent: <AppName>-Webhook/1.0 (e.g., EventReg-Webhook/1.0)
Timeout: 5 seconds (request is aborted if no response)
Retries: None — failed deliveries are logged but not retried automatically.
Allowed hosts: Public HTTPS endpoints only. localhost, 127.0.0.1, 0.0.0.0, and AWS metadata IP (169.254.169.254) are blocked.
Response: Any 2xx status is considered success. Non-2xx responses are logged as warnings.

Testing Your Integration

Save the Integration URL in the Form Constructor.
Activate the form (click Check & Activate → Activate).
Open the form preview or public link and submit a test entry.
Check your webhook receiver logs: you should see a JSON payload matching the structure above.

Common Questions

Why didn’t my webhook receive anything?

Make sure the form is Active (not in Created or Draft state).
Verify the URL is correct and uses https://.
Check that your endpoint accepts POST with application/json.
Look at your server logs for a 5-second timeout or blocked IP.

Can I use a local tunnel (ngrok, Cloudflare Tunnel) for testing? Yes, as long as the public HTTPS URL resolves to your tunnel. Plain http:// is allowed but https:// is strongly recommended.

What if my endpoint returns an error? The system logs the HTTP status code and moves on. There is no automatic retry. You can re-submit the form manually or build a retry mechanism on your side.

Can I send to multiple URLs? Currently only one Integration URL is supported per form. If you need to fan out to multiple systems, use a middleware (e.g., Zapier, Make, or your own relay endpoint).

Are file uploads included? File upload fields are not currently sent in the webhook payload. Only the field metadata is included in data.fields. The actual files remain in the platform’s storage.

Documentation