Setting Up with Zapier

This shouldn't have been that hard, but it was. I mostly blame pronouns.

I'm documenting this here just so I'll remember how to redo it all again later. As usual.

To be clear, an App is what a developer creates so others can use it. A Zap is something a user creates that uses the App and connects it to other Apps.

A subscription is created uniquely for each Zap that a user creates. It is tied to a trigger event which is what kicks off the whole chain of events. In our case, we are actually not receiving any information from anyone else, just sending it out.

When a user, or in our case a merchant, connects TCO merchant to a Zapier account, they do so with an API key to establish their identity.

All subscriptions for a given merchant are tied to that API key. Each time a Zap is turned on or off, that merchant is subscribed/unsubscribed from the related event. Each time a new subscription is created, a new, unique target URL is created. This has to be updated in the TCO merchant data and removed when they are unsubscribed.

Step 1: Create the Zapier Application

• You'll need to be a developer for this, so sign up for that.
• I created a 'Web Builder App' since that was the easiest. Not a JS fan.
• Give it a catchy name that your customers will recognize.
• Add authentication using API keys and Headers.

Step 2: Create a test trigger for authentication

You must create a trigger so that the subscription process can be completed.

• Name it Authentication and give it a description, but just hide it.
• Skip the trigger fields as you don't need to do anything with those.
• "Where Data Comes From" requires only two things

• The Data Source should be set to Polling. This doesn't really poll.
• The polling URL should be set to https://[domain.com]/api/webhooks/auth/zapier

• Save the page.

Step 3: Manage subscribe URL

Select Manage Manage Trigger Settings. Complete the REST Hook Subscribe URL field with:
https://[domain.com]/api/webhooks/subscribe/zapier

Make sure the Test Trigger on this page is set to Authentication which you just created.

Step 3: Authentication

We're using an API key approach, where our app issues a key to each merchant when they want to active web hooks. It's possible for us to add more information for the user to enter when they first authenticate, but that doesn't add any security or validation to the process, so we left it out.

The merchant then uses that key when they connect their TCO account to Zapier. This is a one time operation. We store that key value in a dictionary with the merchant as the merchant may have more than one service connected other than Zapier (such as Microsoft Flow).

This means all endpoints in the /api/webhooks/ routes do not require authentication.

Step 4: Add Scripting for Authentication purposes

The unsubscribe process can be done multiple ways, but the best way is to have Zapier issue a DELETE call and reference an Id that is unique to the subscription. When the subscription is created, TCO will create a unique id for it. That id is stored at Zapier and supplied during the unsubscribe process.

To make that work, skip down the page from Triggers and select Scripting. Use the following code:

'use strict';

var Zap = {
    pre_unsubscribe: function(bundle) {
        bundle.request.method = 'DELETE';
        bundle.request.url='http://[domain.com]/.ngrok.io/api/webhooks/zapier/'+bundle.subscribe_data.webhook_id;
        bundle.request.data=null;
        return bundle.request;
    },

    post_subscribe: function(bundle) {
      bundle.subscribe_data = z.JSON.parse(bundle.response.content);
      return {webhook_id: bundle.subscribe_data.id};
  }
};

Be sure to update the URL showing in the pre_unsubscribe function, the one shown here was used during testing.

Step 6: Create a trigger that will be called by a TCO web hook

• Creating a trigger is pretty straightforward. The first page is all self explanatory.
• There are no trigger fields to be completed on the second page.
• On the Where Data Comes From

• Set the data source is Rest Hooks
• Set the Polling: URL to https://[domain.com]/api/webhooks/zapier/sample/[event-name] where event name is EventTypeEnum.Value inside the TCO system, e.g. invitation.created. Note that no polling of this is done other than during the Zap creation.

• Custom trigger fields URL can be left blank.
• Webhook: Event Name should be also be the EventTypeEnum.Value. It is this value that is sent during the subscription process.
• Skip the Sample Result setting.

Step 6: How the authentication flow works during a Zap creation.

• To create Zaps the merchant has to connect TCO to Zapier. This can be done using the Settings/Connected Accounts option on the Zapier home page. It's also possible to connect an account during the creation of the Zap. This is performed mid-step, but it's the easiest. That process requires that the merchant access TCO and cut and paste their API key into Zapier.
• Using the API key from the connected TCO merchant account, the Zap makes calls to an endpoint on TCO to retrieve sample data.
• For each trigger we offer, we need to create an endpoint to return sample data.
• This sample data allows them to select from the fields that we are going to send when the actual trigger happens
• After the Zap creation is complete, the user is asked to give it a name and turn it ON. When the Zap goes live, it issues a subscribe call to TCO , and passes along the event name it's subscribing to, as well as the target_url that TCO should call when the event occurs.