What 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 list 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.
For integrating 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.
Setting Up the Webhook
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 Form Designer for the form for which you want to add a webhook. If you're not sure how to get there, the easiest way is to click the link in the bottom-left corner of the Form Editor in your Campaign Builder.
Before moving forward, you'll likely want to add an opt-in checkbox to your form; this is best practice for most third-party software, especially email marketing software.
From the Form Designer, click the link at the top that says Manage Integrations.
On the following screen, click the checkbox next to Webhook, then click Send each entry to a webhook URL.
We'll need a webhook URL, so open a new tab and log into your Zapier account. Click the orange Make a Zap! button up top.
Making a Trigger
The next step is to set up a trigger. This trigger happens when an entry is submitted to your ShortStack form. Zapier will ask you now to choose a trigger app - scroll to the bottom and select Webhooks.
Then select Catch Hook, and click the blue Save + Continue button.
You'll see a "Set Up Webhooks by Zapier Hook" screen, which is an optional step. We don't need to set this up for our purposes, so just click the blue Continue button.
At this point, Zapier will give you your webhook URL; click the Copy to Clipboard button - then, switch back over to your ShortStack tab and paste the URL in the field provided.
For the rest of that section, 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
If you scroll down a bit, you'll see the Map Fields 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.
The field keys should automatically be filled in for you. If you add in some 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. Edit that to say opt_in.
Once you've done that, click the blue Save button at the bottom of the page.
With that you're almost done on the ShortStack side. Before heading over to Zapier, you'll want to make sure to Publish your campaign (at least to the web), and submit a form entry so that Zapier has some data to work with for the next step.
Testing the Webhook
The best way to learn what data is sent is to create a test webhook URL and configure your form to post to that URL. If you'd like to test your webhook before moving forward in Zapier, there are several webhook testing services; we recommend PostCatcher, which is free.
At this point, you'll want to switch back to your Zapier tab - you should still be on the "Test Webhooks by Zapier" page. Click the blue OK, I did this 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 the test was successful. Click on the orange Continue button to move forward.
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. More specifically; we need to establish where this data will be sent.
After the last step, you should see in Zapier the Choose an Action App screen. For this example we're using the third-party app Vertical Response. You'll want to click on the icon for the app you'll be using for your action.
You'll now see the "Select App Action" screen. For our example, we're not adding new contacts to an existing list - so we'll select the Create Contact action, then click the blue Save + Continue button. These actions will differ depending on the type of app you're using.
If you hadn't already logged into your third-party app, this is the screen where it would ask you to do so, or you could click the Connect a New Account button if you wanted to add a different one. Once you're logged in and have selected the account you'd like to use from the list, click the blue Save + Continue button.
The following screen is where you're going to map the fields on the third-party app's side of things. For each field listed on this screen, you'll want to start by clicking on the Insert a Field icon in the top-right corner to get your options.
Select the option that matches the field label; in this case, we want to choose the Email option.
The option will show in the field when you're done.
Repeat this process for each field in your ShortStack form. When you're finished, scroll to the bottom and click the blue Continue button.
Once that's done, Zapier is going to want to do another test, this time to test out the app's side of things. If you want to skip the test, you can click Skip Test + Continue - otherwise, click the blue Create + Continue button.
At this point you can double-check the contact in your third-party app to make sure that it was created successfully. If everything is looking good, switch back to your Zapier tab and click the orange Finish button.
You'll now see a page that allows you to name your new Zap, and also a slider switch to turn your new Zap on so that your form can start sending entries to your third-party app. Go ahead and name your Zap, DO NOT TURN ON THE ZAP YET. There's one more crucial thing to set up before turning on the Zap - adding a filter.
Adding a Filter
Remember how you added an opt-in checkbox to your form? You're going to want to filter the people out who don't check that checkbox; you definitely don't want to upset people by adding them to a mailing list that they did not want to be added to.
To start on this, you'll want to look on the left side of your Zapier screen and hover over the line between Steps 1 & 2; click on the plus sign that appears next to Add a Filter or Action, then click the Filter button.
Click the blue Continue button on the "Select Filter" screen, you'll be taken to the page where you can actually set up the filter. Using the down arrows on the right side of each field, select the Opt in field for your first selection, and (Boolean) is true for the second selection. This will ensure that the Zap only captures the form info and sends it on if the opt-in box is checked. Click the blue Continue button when you're done.
At this point, all that's left to do is test the new filter, then turn the Zap on. On the next screen, click the blue Test Filter button. Before doing this, you may want to submit a few more entries to your form, some with the opt-in box checked, and some without - just to make sure the filter is catching them correctly. Once the test is done, you'll see a confirmation screen - click the orange Continue button if everything looks good.
As long as that finishes successfully, you should be all set! You can now flip the switch to turn on your Zap, and you're done setting up your webhook!
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 firstname.lastname@example.org.