Prefill-Webhook

Prefill-Webhook


Overview

The Prefill-Webhook field auto-populates form fields using data fetched from an external service. When a respondent enters a value and clicks the search icon, a request is sent to the configured endpoint. Based on the response, mapped fields in the form are automatically filled, creating a faster and more personalized experience. This reduces manual input, improves accuracy, and streamlines the form-filling process. The form sends the entered value to the service, receives the matching data, and fills the fields as per the prefill setup. Respondents can then review or edit the prefilled details before submitting.

Configuring Prefill-Webhook

To configure the Prefill-Webhook field, create your form and follow these steps:
  1. Navigate to the Builder tab.
  2. In the fields panel, go to Prefill.
  3. Drag and drop the Prefill-Webhook field onto your form to add it.
  4. A configuration popup will appear now with four steps to complete the setup:
    1. Field Configuration
    2. Webhook Settings
    3. Test & Verify
    4. Prefill Mapping
Let's check each step in detail below. 

1. Field Configuration
     Field Configuration

In this section, you will configure the basic field settings:
  1. Enter the Field Label for your Prefill-Webhook field. 
  2. Choose the Field Type. 
  3. The supported field types are Single Line, Number, Email, Phone, Dropdown and Radio. 
  4. Click Next.

2. Webhook Settings

Webhook Settings
In this section, you will configure the webhook:

Webhook Details 

Webhook URL
The Webhook URL is the endpoint where your form will send requests to the external service on search. Enter the full URL of the external service to retrieve the data. 
The following Webhook URL methods are supported:
  1. GET
  2. POST

Authorization Type
Select the desired Authorization Type:
  1. General: Use when the endpoint is public or when you handle authentication via headers or query parameters.
  2. Connections: Use a pre-configured connection from the Control Panel. If you choose Connections, select the appropriate connection from the Connection Name dropdown list. Click the refresh icon if you have recently added a new connection so that it appears in the list. Read more on creating connections.
NotesNote: The Connection Name will only list the existing active connections. Read more about Connections.

Data Retrieval Methods
Retrieval of data from external sources can be done by either
  1. URL Parameters 
  2. Request Body
  3. Custom Header

URL Parameters
URL Parameter sends information to an external service, to retrieve the record to prefill a form when a user enters value in the Prefill-Webhook field of the form.
URL Parameters
During a record search, the webhook will include the URL parameter as a query string. The value entered in the Prefill-Webhook field, if mapped as a URL Parameter, is sent as the query parameter's value. The external service then uses this information to provide the data needed to prefill the form.
Example:  If your Prefill-Webhook field is "Enter your email" and its value is mapped to the URL Parameter email, when a user enters richard@zylker.com in the field and searches, the webhook will send a request like: https://api.zylker.com/getEmpInfo?email=richard@zylker.com

You can add additional information to filter the relevant data. For example, if you add a parameter named department with the value IT, then webhook will send a request like this:
 https://api.zylker.com/getEmpInfo?email=richard@zylker.com&department=IT
You can add additional parameters by clicking the + icon and entering the name and value. You can also add a custom value to a parameter name by clicking Custom Input.

Request Body
Request Body is another way to send information to an external service to retrieve records and prefill the form. The supported formats are JSON and Text. The Request Body is used only with the POST method.
Example - Sample JSON to retrieve record based on a respondent's email and department:
{
  "email": "${zf:SingleLine}",
  "dept": "IT"
}
Request Body

Custom Headers
You can set a custom header name and value to be passed with the Webhook request.Enter the name of the header and the value associated with this header.
Custom Headers

Notes
Note:
  1. The Prefill-Webhook field must be included in either URL Parameters or the Request Body, as it provides the webhook the identifier to retrieve a specific record.
  2. You can add up to five URL Parameters and Custom Headers each. 
  3. You can add up to five form fields in total, combining both URL Parameters and Request Body. Supported field types include Single Line, Number, Email, Phone, Dropdown, and Radio.
Click Next.

3. Test & Verify
Test & Verify

In this step, you can test the webhook and verify that it retrieves the correct data based on the value entered in the Prefill-Webhook field.
  1. Enter the test values in the Fields section.
  2. Click Run Test to execute the webhook.
  3. Review the received response to verify the data is correct.
    Run Webhook Test
Click Next. 

Notes
Note: The Fields section displays all the fields configured in the URL Parameters and Request Body.

4.  Prefill Mapping

The next step is to determine which form fields should be pre-populated with the information from the fetched data.

To map the form fields that you wish to prefill with data from the external service, 
  1. Click Choose Field to add a form field.
    Prefill Mapping - Choose a Field
  2. Click the input text box on the right corresponding to the added form field. 
  3. A popup with the JSON response will open. Identify the keys in the JSON response that contain the data you need and select it for the mapping.
    Select value in JSON response to map

  4. Repeat this for all form fields you wish to prefill.

For Date and Date-Time fields: You have the option to choose the Expected Format. The date value received from the webhook in the chosen format will be converted to the Date Format configured in the form's settings (Settings > General > Date & Time > Date Format) and prefilled in the live form.
Date and Time fields mapping
For Subform fields: If you have any Subform fields in your form, and wish to prefill them, map those Subform fields with the corresponding external service data fields in the same way.
Subform Mapping
Click Save to complete the Prefill-Webhook field configuration. 

Notes
Note: 
  1. You can have a maximum of 50 field mappings in the Prefill Mapping section, including fields mapped within the Subform.
  2. When a form loads with a pre-filled value (via Field Alias) in the Prefill-Webhook field, it triggers the search automatically. Here, the mapped fields will get prefilled via the webhook without the respondent manually clicking the search icon.  
 

 Field Properties    

After you configure the Prefill-Webhook field, the standard field properties will be the same as those of the selected field type (Single Line, Number, Email, Phone, Dropdown, or Radio).
Prefill-Webhook Field Properties


After configuring the field, Prefill Configuration and Search Icon Style can be edited from the properties panel itself later.

Prefill Configuration 

Prefill Configuration displays your prefill data source (in this case, a webhook) within the properties panel itself. For a quick view of your configured prefill, click the Summary button; for editing it, click on Edit button.

 
Prefill Configuration Summary 

Click on the Summary button to view Prefill Configuration Summary. It displays a summary of your configured prefill, including the prefill data source (in this case, a webhook), Webhook URL, HTTP method used (GET/POST), URL Parameters/Headers and Prefill Mapping details. You can quickly view the configuration without reopening the full setup.
Prefill Configuration Summary

 Edit Prefill Configuration

Click the Edit button to reopen the configuration screens and modify the Webhook Settings, Test & Verify section, and Prefill Mapping details if required.

Edit Webhook Configuration

 Search Icon Style  

You can choose how the search action is presented to respondents in the live form using the Search Icon Style property. The search icon can be customized in the following display styles:

 Inline Icon 

The search icon appears directly within the input field, on the right side.
Inline Icon

 Standalone Icon 

The search icon appears as a separate clickable icon right next to the field.

Standalone Icon

 Button 

The search action appears as a dedicated button. On selecting this icon style, the Button Label property will appear. This lets you customize the text displayed on the button (for example, “Search”, “Lookup”, “Fetch Data”).

Button

Notes
Note:
  1. After configuring the Prefill-Webhook field, clicking the search icon in the live form field triggers the webhook and automatically prefills the mapped fields.
  2. The button label cannot be left empty and the maximum length supported is 10 characters.

Info
  1. For Response Formats and Pricing details that apply to all Prefill fields, refer to the Prefill Overview article.
  2. Learn more about whitelist IP addresses.