WebhookPRO

The Webhook action allows you to push form submission data to any URL endpoint using POST, GET, PUT, or DELETE methods as well as adding returned data to your form fields.

Demo

Example Use Cases

• Make a request to an API for data and use the returned data to populate form fields.
• Pre-load a form with statistical data from an endpoint.
• Create a vehicle VIN lookup using an API endpoint.
• Push a form submission to a custom endpoint.
• Push a form submission to a third party that WS Form does not natively integrate with.

Creating a Webhook Action

To create a Webhook action:

1. When editing your form, click the Actions icon at the top of the page. The Actions sidebar will open on the right-hand side of the page.
2. Click the Add  icon to add a new action.
3. Select Webhook from the Action pulldown. A series of settings will appear.

As with all sidebars in WS Form, click the Save button at the bottom to save your changes, or click Cancel to disregard your changes.

Testing Webhooks

A useful way of testing your webhook request is to use the website Webhook.site. Put the unique URL provided in the URL of Endpoint setting (see below), submit your form and you will see the request on the Webhook.site.

Configuring the Webhook Action

The action settings are as follows:

When Should This Action Run?

You can choose to add the post when the form is saved, submitted, or both. If you are running the webhook action using conditional logic we suggest unchecking both of these options.

URL of Endpoint

Enter the URL of your endpoint, e.g. https://mysite.com/my_endpoint.php.

Request Method

Select the request method you would like to use when sending the data to your endpoint. The available options are:

• POST
• GET
• PUT
• DELETE
• PATCH

Content Type

Select the content type you would like to use when sending the data to your endpoint. The available options are:

• JSON (application.json)
• URL Encoded (application/x-www-form-urlencoded)

Field Mapping

Field mapping tells WS Form which of your form fields to send to the endpoint and what the key name should be for the field’s value in your request data.

To map a field:

1. Click the Add  icon at the bottom right of the field mapping section.
2. In the left-hand column, select your form field.
3. In the right-hand column, enter a key name. You can enter a simple key name, e.g. first_name or use dot notation, e.g. person[0].name.first.
4. Repeat this process for each field on your form.
5. Click the Save button at the bottom of the sidebar to save your changes.

Custom Mapping

You can also add custom key/value mappings that are sent to your endpoint.

To add custom mapping:

1. Click the Add  icon at the bottom right of the meta mapping section.
2. Select your form field.
3. In the left-hand column, enter a value. WS Form variables are supported.
4. In the right-hand column, enter a key value. You can enter a simple key name, e.g. first_name or use dot notation, e.g. person[0].name.first.
5. Repeat this process for each field on your form.
6. Click the Save button at the bottom of the sidebar to save your changes.

Header Mapping

Header mapping allows you to add additional HTTP headers to your request.

To add a header mapping:

1. Click the Add  icon at the bottom right of the meta mapping section.
2. Select your form field.
3. In the left-hand column, enter a header name.
4. In the right-hand column, enter a header value.
5. Repeat this process for each field on your form.
6. Click the Save button at the bottom of the sidebar to save your changes.

Process Response

If this is checked, WS Form will process Response Code Mapping and Response Field Mapping.

if this is not checked, WS Form will instruct WordPress not to block the request. Response Code Mapping and Response Field Mapping will be ignored. Note that any errors will be ignored and the webhook request will not wait for a response from the server.

Response Code Mapping

Use the Response Mapping setting to control how HTTP status codes are handled.

To add a mapping:

1. Click the Add  icon at the bottom right of the response code mapping section.
2. In the left-hand column, choose the HTTP code you wish to map.
3. In the right-hand column, choose how to handle the HTTP code.
4. Repeat this process for each HTTP code you wish to map.
5. Click the Save button at the bottom of the sidebar to save your changes.

The available handlers are:

Response Field Mapping

Use the Response Mapping setting to put data returned from your endpoint into form fields. The form data must be returned in JSON format.

To add a mapping:

1. Click the Add  icon at the bottom right of the response mapping section.
2. Select your form field.
3. In the left-hand column, enter a key name. You can enter a simple key name, e.g. first_name or use dot notation, e.g. person[0].name.first.
4. In the right-hand column, choose the form field you want to map this data to.
5. Repeat this process for each field on your form.
6. Click the Save button at the bottom of the sidebar to save your changes.

Authentication

Select the authentication type you would like to use when sending the data to your endpoint. If you select a type, you will be prompted for a username and password.

Timeout

The maximum amount of time in seconds to wait for a response from the endpoint.

SSL Verify

Whether to verify SSL for the request. We recommend keeping this checked.

Use URLs for File Fields

If checked, file and signature fields will be converted to URLs instead of file objects. Multiple files are comma separated.

Ignore Empty Values

If checked, keys with an empty value will not be included in the request.

Convert Arrays to Delimited Text

If checked, fields that have multiple values (e.g. Checkboxes) will be converted to comma separated values.

Cookie Passthrough

If checked, WS Form will pass any cookies received from the form submission through to the endpoint. For security reasons this is only possible with requests made to the same hostname.

Debug

You can use the debug console log to view information about the request and response for a webhook request.