Setup

Formstack supports webhooks which are a way to send form submission data to a specified URL when a form submission occurs. Webhooks can be used in place of or as a supplement to our API.

📘

Testing Webhooks

If you need to test your webhooks, we suggest using a service such as Request Bin.

We send the form submission data through an HTTP POST request as either URL encoded form data or as a JSON string depending on the format you select in the webhook configuration options.

Using unique field identifiers

Post using field names (default)

If you select this option when using webhooks, ensure the form has only ONE usage of each field. If you have multiple uses of one field type, for instance, 'short answer', 'name' or 'email', then only the last occurrence of the field will be sent in the webhook.

Post using field IDs
Please be aware that the 'field key' is a number and not a human-readable text value.

Post with API-friendly field keys
When utilizing this option, you must use unique labels for each of your fields. If you have multiple fields with the same label, regardless of the field type, then only the last occurrence of the label will be sent over.

Example: You have two Name fields on a form and they are both labeled ‘Full Name:’. For both the Post using field names (default) and Post with API-friendly field keys options, only the second occurrence will be passed via the webhook. Say ‘Jane Doe’ is entered in the first name field and ‘John Doe’ is entered in the second, only one name will be passed via the webhook and that value would be ‘John Doe’.

Setup

Webhooks are configured on a form-by-form basis through the form's Settings tab. To add a webhook to your form, simply select your form from the form dashboard and follow the steps below.

1. Select the "Settings" tab on the top of the page
2. Select the "Emails & Redirects" tab on the left
3. From the "After the form is submitted" section, select the "Click here to change" link
4. Once the dialog appears, select "Send Data to an External URL (WebHook)"
5. Enter your webhook configuration options
6. Click "OK" on the dialog and your webhook will automatically save

The webhook configuration options give you several ways to customize how the data is sent to your webhook's URL.

Post using field IDs instead of field names

When submission data is sent to your webhook's URL, the keys used to contain each field are the names of the fields you specified when building your form. If you'd prefer these keys to be the numeric ID of the fields, you can select this option.

Post without sub-field names

By default, when Formstack sends data to your webhook's URL, we identify any complex fields such as the Name field or Address field and separate out their subfields. The submission data for a Name Field, for example, will contain at the very least "first_name" and "last_name" subfields and may contain more depending on the subfields you selected when building your form. When Formstack sends this data, each subfield is the key of an associative array. If you'd prefer a simple string value such as "FirstName LastName", you can select this option.

Post with field type

The submission data being sent to your webhook's URL will always contain the value from the submission for each field on your form. If you'd like to include the field type for each field, you can select this option.

Adding security to your webhooks

We recommend using SSL/TLS on your webhook endpoint to ensure that data cannot be read in transmission. We also allow you to choose one of these additional security options in the webhook settings.

Shared Secret

Specify a shared secret and this will sent along with each request to verify that the request is coming from Formstack. The shared secret is included in the submission data as a field called "HandshakeKey".

HMAC Key

Specify a HMAC key that we will use to sign the webhook payload with so you can verify that it came from Formstack and has not been changed en route to your webhook URL. The HMAC signature is included in the "X-FS-Signature" request header.

{
  "FormID": "23534",
  "Name": {
    "first": "John",
    "last": "Smith"
  },
  "UniqueID": "12345678",
  "HandshakeKey": "the_shared_secret_value_you_used_in_your_webhook_settings"
}

sha256=909a04cfee970d5c0dda83abb3760c3ee02cde0b9583e72c8d4ff0dd5c2239c2

To validate the request with the signature header value, you will need to hash the body of the webhook request with HMAC using the SHA256 hashing function and your shared key.

<?php
$postdata = file_get_contents("php://input");
list ($method, $signature) = explode('=', $_SERVER['HTTP_X_FS_SIGNATURE'], 2);

$expectedSignature = hash_hmac(
  $method,
  $postdata,
  'the_hmac_key_value_you_used_in_your_webhook_settings'
);
if (hash_equals($expectedSignature, $signature)) {
  // Verified
}