What exactly is a Webhook?
A webhook uses an HTTP POST request to send your form's data to a specified URL each time your ShortStack campaign receives a new entry. Webhooks can be used, for example, to send entries to your own server to store in your own database, or they can be used to integrate with a third-party service that accepts HTTP POSTs. The POST occurs when an entry is submitted.
To easily integrate with other services, we recommend Zapier. You can configure a webhook URL as the trigger, and then choose an action from the many services Zapier supports.
Note: Prior to setting up your webhook, you'll want to create an account on Zapier. It's a good idea to check to see if the software you're wanting to use is compatible with Zapier using their App Directory. You'll also want to log into the third-party app you're looking to integrate and have that open in a tab on the side.
Start by navigating to the widget settings of the Form Container Widget where you want to add a webhook. Before you move forward, you'll want to add an opt-in checkbox to your form; this is best practice for most third-party platforms, and it's actually required for some. Then:
- In the widget settings pop-up, open the Advanced section, then click the Configure integrations button in the Integrations subsection.
- In the pop-up that appears, you'll see three options - select Webhook. From there you'll need to add a webhook profile:
In the Select Export Profile pop-up, click the Add button at the bottom.
Configure the settings and the field mappings using the appropriate sections. Some of the information for these will come from Zapier, so we'll tackle that next.
Now, you'll need to open a new tab and log into your Zapier account, then click the orange Create Zap button.
Making a Trigger
The next step is to set up a trigger. This trigger happens when an entry is submitted to your ShortStack form. To reiterate, steps 1-4 below are done within Zapier.
- Zapier will ask you now to choose a trigger app - select Webhooks from the Built-In Tools section.
- In the Event dropdown, select Catch Hook, and click the Continue button.
- The trigger section will appear, but this step (setting up a Child Key) is an optional one we don't need; so just click the Continue button.
- At this point, Zapier will give you your webhook URL; click the Copy button.
- Then, switch back over to your ShortStack tab and paste the copied URL into the Webhook URL field in your Webhook Profile Details pop-up.
- For the rest of the General section of the webhook profile, we'll leave the Content Type and Secret Key fields alone. The Secret Key field comes into play if you're looking to secure your webhook form integrations. If you're looking to do that, you can read a more detailed doc about it here.
Mapping the Fields
Now you'll tackle the Field Mappings area. You'll need to set these up so that your software knows how to store the data from your form once it has been received.
When creating a new webhook profile, all of the standard fields are automatically set up for you. To remove unneeded fields, click the icon on the right of the field you want to remove.
The field keys are automatically set for you. If you add any custom fields, you may need to change the keys for those; one of those you'll want to edit for sure is your opt-in checkbox. It should be set to opt_in. To change any of the field keys:
- Click on the icon to open the Edit Field Map pop-up for that respective field.
- In the Output Field Name field, type in the new key.
- Click OK.
Once you have all of your field mappings looking the way you want, click the Save button at the bottom of the pop-up, Select to use the webhook profile you just set up, and Save again to close the Integration Settings pop-up.
With that you're almost done on the ShortStack side! Before heading back to Zapier, you'll want to make sure to Publish your campaign, and submit a form entry so that Zapier has some data to work with for the next step.
Testing the Webhook
At this point, you'll want to switch back to your Zapier tab - you should still be in the Test section. Click the Test trigger button. Zapier will test your webhook using the data you entered when you submitted the form. This process can take a few minutes, so hang tight. When it's done, you'll see a screen that tells you that a request was found (the request being your form submission), and what data was part of that request. If it all looks correct, click Continue.
Setting Up an Action
Now that we have the webhook and trigger fully established and configured correctly, we need to set up an action that will occur when your form is submitted.
- In Zapier, you should be in the Action section. Click on the icon/name of the app you'll be using for your action. For the purpose of this doc, we'll be selecting MailChimp, as setup for that will be similar to setting up a zap for any other email marketing platform.
- Next, we'll set the event that needs to happen when the webhook is triggered. For our example, we'll select the Add/Update Subscriber event, then click Continue button.
Note: The events available in the drop-down will differ depending on the type of app you're using.
- Click the Sign in button and a window will pop up, allowing you to sign into your chosen platform. This window also tells you what permissions Zapier will have in your account. Once you're signed in, click the Continue button.
- The following screen is where you're going to map the fields - essentially, making sure that the info being sent from ShortStack is being received in a corresponding place in your third-party app. Make sure to add a response for each required field to start, but then map every field for which you're capturing information.
For example: Using Mailchimp, the Audience and Subscriber Email fields are required, so we've set the Audience and then clicked into the Subscriber Email field and selected Email from the Insert Data pop-up. The data will then show in the field. That looks like this:
We're also collecting the first and last name in our example, so we've repeated that process in the First Name and Last Name fields. You'll repeat this for any other data you're collecting in your form.
- Once all of your form fields are mapped, click the Continue button.
- At this point Zapier will want to test the action to make sure everything is working properly. Double-check the data in the item data section to make sure it matches what you'd set up in the previous step, then click Test action.
- A notice will tell you if the action was done successfully, and show you the data that was sent as part of the action. Click Publish Zap.
When the zap is published, it's automatically switched on and your setup is complete! If you need to turn the zap off for any reason, you can go into the zap's settings page and click the on/off slider in the top-right corner.
If you end up running into any issues, or see that the webhook has stopped working, be sure to double-check each setup step. Also make sure no information has been altered on either the Form Widget, or on the third-party app's side. Of course, if you need further assistance, you can always reach out to us at email@example.com.