Create a Custom Integration with WS Form

WS Form includes over 110 integrations with popular third-party services, including email marketing platforms, CRMs, automation tools, payment gateways, spreadsheets, cloud storage platforms, and more.

If the service you want to connect to is not natively supported, you can still create a custom integration using the extensibility features built into WS Form.

This article explains the best ways to create a custom integration with WS Form, including webhooks, WordPress hooks, automation platforms, integration add-ons, and custom validation hooks.

Custom Integration Options

The main options for creating a custom integration are:

• Webhook action
• Run WordPress Hook action
• Make add-on
• Zapier add-on

For validation integrations, you can also use:

• wsf_submit_field_validate
• wsf_submit_validate

Option 1: Use the Webhook Action

The Webhook action is often the best place to start when you want to send WS Form submission data to an unsupported third-party service.

A webhook allows WS Form to push form submission data to a URL endpoint using HTTP request methods such as POST, GET, PUT, DELETE, or PATCH.

When to Use a Webhook

Use the Webhook action when the service you want to connect to provides an endpoint that can receive data.

Common use cases include:

• Push a form submission to a custom endpoint
• Push a form submission to a third-party service that WS Form does not natively integrate with
• Make a request to an API and use returned data to populate form fields
• Pre-load a form with statistical data from an endpoint
• Create lookup functionality, such as a vehicle VIN lookup
• Send leads, enquiries, orders, or registrations to an external system

Webhook Configuration

When configuring the Webhook action, you can choose when the action should run, enter the endpoint URL, choose the request method, and select the content type.

Supported request methods include:

• POST
• GET
• PUT
• DELETE
• PATCH

Supported content types include:

• JSON
• URL encoded

Field Mapping

The Webhook action uses Field Mapping to control which form fields are sent to the endpoint.

For each field mapping, you select a field from your form and enter the key name that should be used in the request data.

Example field mappings might include:

• Name field mapped to name
• Email field mapped to email
• Phone field mapped to phone
• Company field mapped to company

You can use simple key names, such as first_name, or more advanced key names using dot notation, such as person[0].name.first.

Custom Mapping

Custom Mapping lets you send additional key and value pairs to the endpoint.

This is useful if you need to send static values, WS Form variables, tracking values, hidden values, or other data that is not directly mapped from a single form field.

Header Mapping

Header Mapping lets you add HTTP headers to the request.

This is commonly used for:

• API keys
• Authorization headers
• Content negotiation
• Custom headers required by the endpoint

Processing the Webhook Response

The Webhook action can process the response returned by the endpoint.

If Process Response is enabled, WS Form can use Response Code Mapping and Response Field Mapping.

Response Code Mapping lets you decide how different HTTP status codes should be handled. For example, a response code can be ignored, used to process response field mapping, used to throw an error, or used to halt action processing.

Response Field Mapping lets you map JSON data returned from the endpoint back into form fields.

This is useful for integrations that return:

• A customer ID
• A quote value
• A status message
• A reference number
• A validation result
• Data that should be used by later actions

Testing Webhooks

When building a webhook integration, it can be useful to test the request using a service such as Webhook.site.

You can enter the test URL as the webhook endpoint, submit your form, and inspect the request that WS Form sends.

Option 2: Use the Run WordPress Hook Action

The Run WordPress Hook action lets developers run a WordPress action or filter when a user saves or submits a form.

This is a powerful option when you need to run custom PHP code as part of the form submission process.

When to Use Run WordPress Hook

Use Run WordPress Hook when you need more control than a webhook or automation platform provides.

Common use cases include:

• Run custom PHP code when a form is submitted
• Modify submission data before other actions run
• Connect to a proprietary system
• Write data to a custom database table
• Call one or more APIs
• Set a spam level
• Return a custom message
• Redirect the user
• Halt action processing

Hook Types

The Run WordPress Hook action can run either:

• A filter using apply_filters
• An action using do_action

When configuring the action, you enter the hook tag that you want WS Form to run.

Action Priority

You can choose when the hook should run:

• Before submission created
• Before other actions
• After other actions

Use Before submission created or Before other actions if you need to manipulate field values before other actions run.

Use After other actions if you need to use data created by another action.

Example WordPress Filter

The following example shows the general pattern for using a filter with the Run WordPress Hook action.

add_filter('wsf_filter_tag', 'wsf_filter_function', 10, 2);

function wsf_filter_function($form, $submit) {

	$meta_key = 'field_123';

	$field_value_old = $submit->meta[$meta_key]['value'];

	$field_value_new = str_replace('replace_this', 'with_this', $field_value_old);

	$submit->meta[$meta_key]['value'] = $field_value_new;

	return $submit;
}

In this example, field_123 should be changed to match the ID of the field you want to work with.

Option 3: Use an Automation Platform

Automation platforms are a good option if you want to connect WS Form to another app without writing custom code.

WS Form provides add-ons for automation platforms such as Make and Zapier.

Make Add-on

The Make add-on allows you to integrate WS Form submissions with thousands of apps using Make scenarios.

Make was formerly called Integromat.

To use the Make add-on, you create a scenario in Make, choose the WS Form submission trigger, connect Make to WS Form using the API URL and API key from the WS Form Make settings, and choose the published form you want to use.

Make can then use your form fields and submission fields in filters and mappings.

Zapier Add-on

The Zapier add-on allows you to send WS Form submissions to Zapier.

To use the Zapier add-on, you create a Zap, choose the WS Form New Submission trigger, connect Zapier to WS Form using the API URL and API key from the WS Form Zapier settings, and choose the published form that should trigger the Zap.

Zapier can then pass WS Form submission data to other apps.

Important Notes About Make and Zapier

For Make and Zapier integrations:

• You need WS Form PRO.
• The add-on must be installed and licensed.
• You need at least one published form.
• You need at least one submission to help configure the scenario or Zap.
• The WordPress REST API must be enabled and accessible so Make or Zapier can retrieve submission data from your site.

Example Automation Workflows

Automation platforms are useful for workflows such as:

• Create a CRM contact
• Add a subscriber to an email marketing list
• Create a task in a project management system
• Add a row to a spreadsheet
• Send a notification to a team communication tool
• Pass form submission data to another app in a multi-step workflow

Custom Validation Integrations

Some integrations need to validate data before the form submission is accepted.

For example, you might need to check an email address, verify a membership number, perform a fraud check, or validate data against an external system.

WS Form provides validation hooks that allow developers to add custom server-side validation.

Field-Level Validation

Use wsf_submit_field_validate when you need to validate each field as a form is submitted.

This filter hook receives information such as the field ID, submitted field value, repeatable section index, post mode, and partial submit object.

Use field-level validation for:

• Email address validation
• Phone number validation
• Disposable email blocking
• Username availability checks
• Membership number validation
• Field-specific API checks

If validation fails, your hook function adds one or more errors to the error action array and returns it to WS Form.

Errors can be shown as field invalid feedback, form messages, or redirects.

Field Validation Example

add_filter('wsf_submit_field_validate', 'my_field_validation', 10, 6);

function my_field_validation($field_error_action_array, $field_id, $field_value, $section_repeatable_index, $post_mode, $submit) {

	if($post_mode !== 'submit') {

		return $field_error_action_array;
	}

	if($field_id === 123 && empty($field_value)) {

		$field_error_action_array[] = 'Please enter a value for this field.';
	}

	return $field_error_action_array;
}

Submission-Level Validation

Use wsf_submit_validate when you need to validate the full form submission.

This filter hook is useful for validation that depends on more than one field or on business rules that apply to the submission as a whole.

Use submission-level validation for:

• Cross-field validation
• Duplicate submission checks
• Customer record validation
• Fraud checks
• Eligibility checks
• Custom business rules

If validation fails, your hook function adds one or more errors to the error action array and returns it to WS Form.

Submission Validation Example

add_filter('wsf_submit_validate', 'my_submit_validation', 10, 3);

function my_submit_validation($field_error_action_array, $post_mode, $submit) {

    if($post_mode !== 'submit') {

        return $field_error_action_array;
    }

    $validation = false;

    if(false === $validation) {

        $field_error_action_array[] = array(
            'action' => 'message',
            'message' => 'The submission could not be validated.'
        );
    }

    return $field_error_action_array;
}

Which Custom Integration Method Should You Use?

Recommended Approach

For most custom integrations, start with the simplest option first.

1. Check whether WS Form already has a native integration add-on for the service.
2. Use the Webhook action if the service provides an endpoint that can receive data.
3. Use webhook response mapping if the endpoint returns JSON data that should be added back to the form.
4. Use Make or Zapier if you want a no-code workflow that connects WS Form to other apps.
5. Use the Run WordPress Hook action if you need custom PHP logic during form processing.
6. Use wsf_submit_field_validate or wsf_submit_validate if your integration needs to validate data before the submission is accepted.

Conclusion

WS Form is designed to be extensible, so you are not limited to the integrations that are available out of the box.

For many custom integrations, the Webhook action is the best starting point because it can push submission data to an endpoint, map selected fields to request keys, add custom mappings and headers, and process returned JSON data.

For no-code workflows, use the Make add-on, the Zapier add-on, or another WS Form integration add-on.

For developer-led integrations, use the Run WordPress Hook action or the WS Form validation hooks to build custom PHP processing and server-side validation.