Formstack (OAuthV2 & REST Hooks)#

This example will walk you through creating a developer app that uses REST Hooks for a trigger that subscribes and unsubscribes a callback and waits for the data to come in. To make the example real, we'll be implementing the actual Formstack API. Let's get started!

Quick Preparation Checklist#

If you plan to follow along, it is recommended you set up everything beforehand and keep these resources open and ready for quick access.

Getting Started#

To get started, go to the Developer Platform and click the "Create App" button. You'll be asked to give a title and a brief description. After you submit, you should find yourself with a fresh app:

https://cdn.zapier.com/storage/photos/dd43208410e0ffe3f4edc2b316bdb4a4.png

Next, you'll need to complete all the required steps to authenticate with OAuthV2! You can read a more detailed OAuth V2 guide here, but we'll cover the basics here. First, you'll need to create your developer app in Formstack:

https://cdn.zapier.com/storage/photos/57ac50c03e310c2daa5a4aae0cbd0006.png

To get your redirect URI, don't forget to set up your authentication settings, if you click the below button you can start an automated walkthrough that will help you get the basics set up:

https://cdn.zapier.com/storage/photos/b33516a2c469757a0240f82fd68edc6b.png

And at the very end of that walkthrough, you will be able to input the information given to you from Formstack for your specific developer app:

https://cdn.zapier.com/storage/photos/cb2f685b45250306c6ea1884f50a5251.png

First Trigger and Test Trigger#

Next up we'll want to create our triggers. For this Formstack example, we're going to create two triggers which will be closely intertwined!

  • New Form, will poll a JSON API to return a list of forms. We'll reuse this as the test trigger as well.
  • New Entry, will subscribe/unsubscribe a webhook to get notifications of new entries for a form.

The first trigger will test our authentication mechanism. The first trigger you create will be a test by default, we have a handy button to get started:

https://cdn.zapier.com/storage/photos/e63bd6a12406ef571f227e3af4c8030b.png

Which will bring you to the basic details form about the trigger you are creating. Let's create the Form trigger, it is worth reviewing the Formstack Developer Documentation on the GET /forms endpoint which we'll be using to power the trigger.

https://cdn.zapier.com/storage/photos/f5198e46d4edbb2d3b9e1179b98f8037.png

Since we don't need any other information to make this trigger tick, we can skip trigger fields. Trigger fields just add extra information for the trigger which you can use in the URL or in scripting. Our next trigger will use Trigger fields, so just skip for now!

https://cdn.zapier.com/storage/photos/7259817ddda8c022e98b0dca7fbe3ac3.png

Since we know the URL to retrieve the list of Forms from the Formstack Documentation, it is as simple as pasting https://www.formstack.com/api/v2/form.json directly into the Polling URL. You can skip the custom fields here, they are very rare for triggers!

https://cdn.zapier.com/storage/photos/bf2bed43c66d1ce9c9bb6b3e65e92cff.png

You have everything you need to actually use your app, so now is a great time to test your app! Since all developer apps are available immediately on your account you can just visit your editor and use your app just like any other app Zapier supports!

REST Hook Trigger#

Now it's time for the main attraction! This is what this example is building up to, but first we need to collect a little information about the REST Hook or webhook subscription we can create. For that we'll turn to the general Formstack documentation for webhooks and Formstack's documented webhook endpoints.

Here are the pieces we'll need in this step:

  • The subscribe URL which looks something like https://www.formstack.com/api/v2/form/{{form_id}}/webhook.json
  • The unsubscribe URL which looks something like https://www.formstack.com/api/v2/webhook/{{webhook_id}}.json

First thing is first, we'll we'll need to set those subscription URLs up at the app level, you should see a button to manage your trigger settings.

https://cdn.zapier.com/storage/photos/05cf36ab31fe5fd8639d12045ade3681.png

Go ahead and paste the above URLs into the form and save the settings:

https://cdn.zapier.com/storage/photos/79c5156f041d75e23805bf83eea6a1dc.png

Next up is the big event: let's create the trigger that will use those subscription URLs! Click your add trigger button and fill out the basic information like so:

https://cdn.zapier.com/storage/photos/75d6597a700ca86889104c60be35e518.png

Now comes trigger fields, as you recall, in order to make set up the webhook subscription we need a form_id, luckily Zapier has some tools that makes it easy to make dynamic dropdown's that are powered by other triggers. It just so happens we've already made a trigger for this called "New Form". Let's just show you and recap after!

https://cdn.zapier.com/storage/photos/646c14a2bd081273c84f14a2d96b2e35.png

https://cdn.zapier.com/storage/photos/1b3d49f33560cd96b98437c0db9f626f.png

There are a few things going on, but the two most important are "Key" and "Dynamic Dropdown"

  • Make sure to reuse the Key form_id from the subscribe URL when making the trigger field. This pattern is fairly common and Zapier will stitch them together for you.
  • For the Dynamic Dropdown, there are three parts separated by a .:
    • trigger_key which references which trigger by key you'd like to us.
    • field_id which key from each object is the one we're interested (in this case it is the form_id we want).
    • field_name which key from object is the nice human readable version (in this case it is just name).

Both field_id and field_name are plucked from the JSON response that we get, for example, in this screenshot for the editor:

https://cdn.zapier.com/storage/photos/04a15f4e2145d492f15124ba4adcf6a0.png

The left values are the name and the right values are the id. When a user selects an item, we'll display the name but store the id as well for use later in URLs!

Next up is actually telling this trigger to use REST Hooks and our subscription URLs as the way it grabs data, you can do this on the next step after saving your Trigger Field:

https://cdn.zapier.com/storage/photos/21a4386bbfbfbeae76553a1c8f4175c6.png

You can provide an optional polling URL or sample data with REST Hooks, but Zapier will handle the subscription process for you when the user needs some sample data. If either of those two options are available, we'll try and use them.

Next up is making sure that the request we send to Formstack for subscribe and unsubscribe are correct. That means we'll need to use our scripting feature to write some custom code to modify the requests before we send them. Just use the "Edit Code" button to start!

https://cdn.zapier.com/storage/photos/ce5b8e75871cc50e8cb9d00f395b9c39.png

The three methods we'll need to use are:

  • pre_subscribe - ensure the request to subscribe matches what Formstack expects.
  • post_subscribe - ensure Zapier can store the data to identify the webhook.
  • pre_unsubscribe - ensure Zapier can unsubscribe from the identified webhook.

Again, we are going to reference the Formstack documentation for creating and removing webhooks to understand the format needed for both pre_ calls. Check out the code snippet below for a better understanding:

var Zap = {
    pre_subscribe: function(bundle) {
        bundle.request.method = 'POST';
        bundle.request.headers['Content-Type'] = 'application/x-www-form-urlencoded';
        bundle.request.data = $.param({
            url: bundle.subscription_url,
            append_data: 1
        });
        return bundle.request;
    },
    post_subscribe: function(bundle) {
        // must return a json serializable object for use in pre_unsubscribe
        data = JSON.parse(bundle.response.content);
        // we need this in order to build the {{webhook_id}}
        // in the rest hook unsubscribe url
        return {webhook_id: data.id};
    },
    pre_unsubscribe: function(bundle) {
        bundle.request.method = 'DELETE';
        bundle.request.data = null;
        return bundle.request;
    },
};

Now, you are ready to hop back to the editor and test the trigger properly! If you check out step 6 and click the You should see a popup that takes a second to complete as it performs the subscribe step:

https://cdn.zapier.com/storage/photos/fe33ced2301095d83c11d3194d2be59c.png

Just close that popup and we'll perform the unsubscribe step for you. Now you can go back to your developer app, check out the request logs and see the POST and DELETE requests corresponding to the popup.

https://cdn.zapier.com/storage/photos/715bdc12d4ae72b0af14636923037d16.png

Note! This is the exact same process that will happen when a zap is turned on or off!

Now that you've gotten the subscription process down, we need to actually catch some data from the webhook! The process is very simple:

  1. Go back to the editor.
  2. Get the popup again in step 6.
  3. Submit the chosen form in Formstack.
  4. Wait. Don't close the popup!

You should see something like this once we catch the data:

https://cdn.zapier.com/storage/photos/07ec4115260ad8683345ed7445d9d410.png

And if you click the resulting example you should see the data that we caught!

https://cdn.zapier.com/storage/photos/82d8a5295c054fedaf9ea0c8bed908ff.png

You can use the catch_hook scripting method to further cleanup data (like the name and address fields that are lumped together), but that is outside the scope of this tutorial. Also, you can view your HTTP logs in your developer app for more logs on hooks in addition to normal HTTP.

Congratulations! You have a working Formstack application that:

  • Uses OAuth V2.
  • One polling trigger (reused for testing).
  • One REST Hooks trigger.
  • Scripting or custom code around subscribe/unsubscribe calls.

Be sure to check out our other examples for more details on doing other interesting things with Zapier's developer platform!

↑ Was this documentation useful? Yes No
Get Help