Advanced webhooks automation with the Zapier Platform interface

Once you start using webhooks it's easy to see how powerful they are, and to search for new ways to use them. Webhooks let apps send automated messages or information to other apps, and help online accounts communicate. 

This is one reason why Zapier has its own webhooks app—to make it easier for you to automate just about anything. (Note: You need a paid Zapier account or to be in your trial to use the Webhooks by Zapier app.)

​Webhooks by Zapier supports a wide range of incoming and outgoing HTTP requests that can help you create Zaps in a no-code environment. But sometimes you might need features it alone can't provide, like:

• Authentication credential security 

• Sending Notification Webhooks with no payload

• Payloads (either original or response) requiring pre- or post-processing

• Advanced Error handling

• REST Hook subscriptions

To support these features (and many more), we developed our Platform UI. It provides an approachable graphical user interface for these more feature-rich HTTP requests and allows a person to create an app that encapsulates this functionality.

When you create an app using the Platform UI you'll need to decide if you want the app to be private or public:

• A public app is one that you'd like published in the App Directory and made available for general use. This involves a thorough Zapier review process and is how most of the apps in our directory were developed.

• A private app is one that you want to use in your own Zapier account or share with team members or clients. It has no review requirements, but still allows you to leverage all the features of the Platform UI. We’ll focus on private apps here, exposing the features that let you build your own Webhooks app to communicate with your HTTP API.

Let’s go into some details about each of these features.

Authentication:

Zapier’s Platform UI application supports several authentication methods to connect to your HTTP API, including the following:

• Basic

• API Key

• Digest

• Session

• OAUTH 2

It presents a user interface to create input fields that might be required. Here is an example of a Digest authentication configuration:

It also gives you a step-by-step model for implementing more complex auth workflows, especially OAuth v2. You can follow the steps we have here in concert with your HTTP API documentation and quickly get a configuration set up and tested:

Once you have the authentication flow created for your app, you get these additional benefits:

1. When you add your new app to a Zap or your Zapier account, you’ll enter your credentials and go through the authentication flow you created for your app. That authentication can be re-used in any Zaps that need access to your HTTP API. You don’t have to re-enter these credentials for each Zap.

2. If you need to refresh these credentials (after a password change, for example), then you do it in the My Apps section of your Zapier account. Once that's done, all Zaps that use the authentication will be updated.

3. Credentials are not presented in your Zap History, but stored in a secure repository and censored in all accessible developer logs.

4. If you have other users who need access to your app, they use their own credentials to create their authentication, not yours.

5. If you are part of a Zapier team or companies account, you can share your authentication without sharing your credentials.

No-payload webhooks

Many HTTP APIs use webhook POSTs to alert a service that something has happened, but don’t include any usable data. The Zapier webhook app expects a usable payload to pass on to the next step in a Zap.

In a Platform UI, you can set up triggers which listen for these POSTs, without requiring that they contain this usable data.

The Platform UI processes trigger POST payloads in a Perform function where it outputs a default bundle.cleanedRequest object.

You can easily override this default by outputting your own standard JSON formatted success message, like this:

Once a Zap is created with this trigger, it will run each time you POST to the specific webhook URL that it provides, independent of the payload sent.

Your HTTP payload requires pre or post-processing

Much like the scenario above, sometimes an HTTP payload needs to be adjusted to be used in another Zap step, and there is no way to change this data on the HTTP API side. If you are using the standard Webhooks by Zapier app, this usually means you’d also need to add a Code by Zapier step to the Zap in order to do this post-processing. In the Platform UI, you can instead add this code directly to your app. In a trigger, you’d again modify the Perform function, manipulating the bundle.cleanedRequest object in Javascript to make sure it has the data you need.

As an example, your HTTP API response might always provide a time value in seconds, but you usually need hours in your Zap. You could add a Code by Zapier step to your Zap (and to each Zap that uses this API response), or you could add it directly to your app. 

The response payload looks like this:

{

“name”: “Fred Flintstone”,

“event”: “Dinosaur Race”,

“time”: 6347

}

To add an hour property so it’s available as an output field for other steps, add this code snippet to the Perform function:

The result is this hours field available for mapping in our Zap:

Code can also be added before an HTTP request. This allows you to modify the incoming data to fit what your HTTP API requires. Rather than have multiple Code by Zapier steps surrounding a Webhooks by Zapier step, your app can encapsulate both the code and the request, making it much simpler to use in your Zaps.

Error handling

Unfortunately, errors sometimes happen when using HTTP APIs. Trapping these errors and making decisions based on the error type can make a Zap more resilient. This is especially true with POSTs to Zapier, as the standard response is 200, even if the Zap can’t process the request. More details on why this is here.

The Platform UI allows you to tweak this standard error handling. An example:

Let’s say an API returns this message when a Zap makes too many requests:

{ error: { message: "Rate limit. Set the next task in 60 seconds", code: 500 } }

Unfortunately, it also returns the HTTP status code of 200, so Zapier’s standard error handling would not catch this. An app can, though. If this was a Search Action, the Platform UI presents this UI for configuration:

We can switch to Code Mode to configure how it handles errors. When we do this we get default code that can be modified, including the throwForStatus line:

That line is what usually handles the errors for us, but in this case the API’s 200 response is not recognized as an error, so we need to do our own error handling.  The resulting code looks like this:

When the Zap runs and gets this specific response, it now errors instead of continuing:

This enables the Zap to be manually replayed, or, if auto-replay is enabled, the request will be retried automatically.

There are many scenarios where an HTTP API might provide an error code/message that needs to be re-interpreted to be used correctly in a Zap. By adding some extra handling in Code Mode you can catch these edge-cases and redirect them to the behavior you want.

REST Hook subscriptions

The Platform UI supports both a static webhook interface for Zapier triggers, as well as a full subscription configuration for REST Hooks.

If you want to use a static webhook, leave these subscription fields blank:

When a Zap is created with this trigger, a hook URL is also created and exposed to the user so that it can be configured in your HTTP API service:

If your HTTP API supports dynamic REST Hooks, you can enter your subscribe and unsubscribe URLs (along with any query parameters/authentication that might be required).

When you create a Zap with this trigger, the REST Hook subscription is created when the Zap is enabled, and is torn down when the Zap is turned off. The hook URL is not exposed to the user, but you can add fields that would help users determine what the specific subscription is for:

More about the Platform UI

While the Platform UI can help you expand on how you use webhooks, there are some limitations:

• You can’t use it for downloading or uploading files to your HTTP API.

• Zapier has a throttle for private apps. By default, this is 100 calls every 30 seconds. If you distribute your app widely, or have it used by many members of your team/companies account and need to increase this limit, get in touch with Zapier support.

• The Zapier Webhook app supports the concept of “forking” for Actions where the response is an array. The Platform UI will parse the array, but only run your Zap once for this type of payload.

The Platform UI can help you go beyond the basic functionality of the Webhooks for Zapier app. It allows you to extend your own Zaps without the need to customize each one, and then share them with team members or clients.