The Webhook action pushes form submission data to any URL endpoint using POST, GET, PUT, PATCH, or DELETE. It can also write data returned by the endpoint into 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 split across three tabs: Request, Payload, and Response.

When Should This Action Run?

Choose when the webhook runs. The options are:

• Form Saved
• Form Submitted

Form Submitted is checked by default. If you are running the webhook action using conditional logic, uncheck both options.

Request

URL of Endpoint

Enter the URL of the endpoint to send data to, for example https://mysite.com/my_endpoint.php. The field defaults to https://.

WS Form variables can change the path or query string only. They cannot change the scheme, host, or port.

Method

Select the HTTP request method. The available options are:

• POST (default)
• GET
• PUT
• DELETE
• PATCH

Content Type

Select the content type. The available options are:

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

Authentication

Select the type of authentication. The available options are:

• None (default)
• Basic

If you select Basic, the Username and Password settings appear. WS Form variables are supported in both.

HTTP Header Name/Values

Add HTTP header names and values to the request. WS Form variables are supported.

To add a header:

1. Click the Add icon at the bottom right of the HTTP Header Name/Values section.
2. In the Name column, enter the header name.
3. In the Value column, enter the header value.
4. Repeat this process for each header you want to send.
5. Click the Save button at the bottom of the sidebar to save your changes.

Timeout

How long the connection should stay open, in seconds. Leave this blank to use 15 seconds. WS Form only waits for a response when Process Response is checked.

SSL Verify

Whether to verify SSL for the request. This is checked by default. We recommend leaving it checked.

Cookie Passthrough

If checked, cookies from the form submission are passed through to the API request. This only applies when the request is to the same hostname. This is unchecked by default.

Payload

Field Mapping

Map WS Form fields to endpoint keys. Each row has three columns: Form Field, Key, and Type.

To map a field:

1. Click the Add icon at the bottom right of the Field Mapping section.
2. In the Form Field column, select your form field.
3. In the Key column, enter a key name. You can enter a simple key name, for example first_name, or use dot notation, for example person[0].name.first.
4. In the Type column, choose how the value is sent. Source sends the field value as-is. String, Integer, Float, and Boolean cast the value to that type.
5. Repeat this process for each field you want to send.
6. Click the Save button at the bottom of the sidebar to save your changes.

Custom Mapping

Map custom values to endpoint keys. Each row has three columns: Key, Value, and Type. WS Form variables are supported.

To add a custom mapping:

1. Click the Add icon at the bottom right of the Custom Mapping section.
2. In the Key column, enter a key name. You can enter a simple key name, for example source, or use dot notation, for example meta.campaign.
3. In the Value column, enter the value to send.
4. In the Type column, choose Source, String, Integer, Float, or Boolean.
5. Repeat this process for each custom value you want to send.
6. Click the Save button at the bottom of the sidebar to save your changes.

Repeaters to Arrays

If checked, repeaters are turned into arrays instead of being comma separated. This applies to field mappings only. This is unchecked by default.

File Format

Choose how file fields are sent. This includes file, signature, and media capture fields. The available options are:

• Base64: files are sent as Base64. Multiple files are an array.
• File Objects: files are sent as file objects.
• URLs (default): files are sent as URLs. Multiple URLs are comma separated.

Convert Arrays to Delimited Text

If checked, fields that have multiple values (for example checkboxes) are converted to delimited text. This is checked by default. The delimiter is set in Array Delimiter.

Array Delimiter

The character used when an array is converted to delimited text. This setting is shown when Convert Arrays to Delimited Text is checked. The default is a comma (,).

Deduplicate Arrays

If checked, multiple mappings to the same key are deduplicated. This is unchecked by default.

Ignore Empty Values

If checked, keys with an empty value are not included in the request. This is unchecked by default.

Response

Process Response

If checked, WS Form processes response code mapping and response field mapping. This is checked by default.

If this is not checked, WS Form does not wait for a response and errors are ignored. Response Code Mapping and Response Field Mapping are hidden.

Response Code Mapping

Add handlers for specific HTTP status codes. This setting is shown when Process Response is checked. Each row has two columns: Code and Handler.

A new webhook includes these mappings:

A status code that is not mapped is ignored.

To add a mapping:

1. Click the Add icon at the bottom right of the Response Code Mapping section.
2. In the Code column, choose the HTTP status code.
3. In the Handler column, choose how to handle that code.
4. Repeat this process for each HTTP status code you want to map.
5. Click the Save button at the bottom of the sidebar to save your changes.

The handlers are:

If you use Throw error, you can turn on Form Submission Error Email in WS Form settings to have the error details emailed to you.

Response Field Mapping

Map values in the endpoint response to WS Form fields. The response must be JSON. This setting is shown when Process Response is checked. Mapping runs only for status codes whose handler is Process Response Field Mapping.

Each row has two columns: Key and Form Field.

To add a mapping:

1. Click the Add icon at the bottom right of the Response Field Mapping section.
2. In the Key column, enter the key from the JSON response. You can enter a simple key name, for example first_name, or use dot notation, for example person[0].name.first.
3. In the Form Field column, choose the form field to populate.
4. Repeat this process for each value you want to map.
5. Click the Save button at the bottom of the sidebar to save your changes.

Debug

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