How to get started with Webhooks by Zapier

A Brief Introduction to Webhooks

Zapier fully supports webhooks, and though they can be a little overwhelming at first they can be extremely powerful. The easiest way to think of webhooks is as notifications. At their simplest, they carry a payload of data which is usually a single record that has been created or modified, although some apps will send along multiple records at once in the name of efficiency.

There are three common serialization formats that you will commonly see: form-encoded, JSON, and XML. Below are examples of each, respectively:

first_name=Alex&last_name=Riley&age=27

{
    first_name: Alex,
    last_name: Riley,
    age: 27
}

first_nameAlex/first_name
last_nameRiley/last_name
age27/age

Note: we will do our best to recursively parse nested XML and JSON for convenience. You can disable it by setting the header X-Recurse-Parse: false.

It is important to be familiar with each, as most apps have different standards though some have options, so you can experiment a bit. Don't worry too much though, Zapier handles all of them just fine!

Note: if a completely empty webhook request is sent to your Zap, it will be ignored. When you send the webhook, make sure to add something in the payload (or the url parameters if it's a GET request) so the Zap can trigger.

Once you have a payload, you need somewhere to send it. Usually its to a special URL where a server is waiting to interpret the payload and do something with it. Usually that is a server you control, but in the case of Zapier, its a server we control on your behalf. When you create a new Zap with a webhook enabled trigger, we will generate a brand new URL for your use, sort of like this one:

https://hooks.zapier.com/hooks/catch/1234567/f8f22dgg/

Once you have the URL, you'll be able to provide it to the triggering app. After you do that, we should start receiving payloads whenever the app sends them.

The URL is secured by obscurity. It is almost impossible to guess the combination of the number and code in the URL. But if you make the URL public (e.g. in front-end JavaScript) anyone who finds it will be able to spam it and trigger your Zap. Treat it as a password or any other secret!

Also, Zapier can do the inverse, you can give us a URL and we can push a payload to it. But more on actions later, first, let's keep talking about triggers.

 

Need an Empty Response? Enable Silent Mode

The webhook URLs will respond with JSON or XML:

Some apps get confused and would like to receive an empty body. To do this, add /silent to the end of the URL.

 

Accessing Nested Elements

Commonly the JSON packet sent to a webhook will contain nested elements like the below example:

{
  result: {
    contract_winner: {
      first_name: Homer
  }
}

Even if we specify results as the root element we still need to get at the first_name attribute. We can do this by entering {% templatetag openvariable %}contract_winner__first_name{% templatetag closevariable %} as the field. When we parse JSON packets sent to us we flatten nested attributes and place a double underscore between them.

Also note that if you create a webhook, save it, send some data to it and then edit it you should be able to use the previous requests as sample data.

Debugging Triggers

We do our best to make webhooks "just work" for you, but we can't predict all the wacky ways apps might choose to implement webhooks. Sometimes, you just have to break out a few debugging tools and see what is going on under the hood.

The simplest place to start is Zapier itself. After you've started your Zap and have configured the webhook URL, we start listening. Even if you don't unpause your Zap, we still track the payloads we get to make it easier for you to debug. You can see them by clicking "Load Samples" on step 4, and we'll also pull keys into step 2 to make it easier to map. Here's how to make sure you see the new payloads:

1. Create your Zap and configure your webhook URL but don't enable your Zap quite yet!
2. Go into the triggering app and do something to trigger a webhook (usually that means create a record of some sort).
3. Return to Zapier and click "Load Samples" or "Reload Samples" in step 4.
4. Do you see the new values coming in? Congrats! You can finish editing your Zap and enable it.

If you didn't see the samples, then we need to do a little more debugging. Let's try the next step.

Generating Your Own Requests

Sometimes, you'd like to trigger Zapier webhooks on your own without involving a third party app. There are a few tools that help you do that (like curl) but we generally recommend a app like Postman.

When using curl or hurl.it, we work best with POST requests with JSON payloads. Here's a quick curl example to get you going:

curl -v -H Accept: application/json \
        -H Content-Type: application/json \
        -X POST \
        -d '{first_name:Alex,last_name:Riley,age:27}' \
        https://zapier.com/hooks/catch/n/Lx2RH/

Inspect the Requests

Next, we need to see if the webhooks are even getting sent, or what sort of weird format they might be in. For that, we like to recommend a app like this one. It doesn't try to interpret the payloads, it just prints them to your screen as it receives them, making it easy to see what is going on. Copy and paste the URL you are given as your Unique URL into the Webhooks URL field, and then run the Test to send that information along, and refer to it on the testing page.

Now, log back into your triggering app's settings and replace the old Zapier webhook URL with the new RequestBin URL. Then, take the steps necessary to trigger the webhook once again (usually creating a record of some type). After you do that, simply refresh your RequestBin page and take a look.

Now the question is: did you see any new records show up?

If yes, that means Zapier is getting the payloads but couldn't interpret them properly. We would recommend you check out our blog post on using the Developer Platform for processing more complicated payloads.

If no, that means the app isn't sending the payload! Usually this is just a misunderstanding as they may not have webhooks enabled for the records you want, but sometimes you just need to check another checkbox somewhere, so you might trying contacting that app before contacting us.

Debugging Actions

Like we mentioned earlier, Zapier also can send webhooks, not just receive them. That makes it easy to pipe data around the web, especially if you don't want to muck around with setting up connecters to various APIs: you can just dump the data in a nice format via Zapier.

Sending webhooks via Zapier is much more complicated than receiving them via Zapier as you are in charge of interpreting the payloads yourself. If you are a programmer, this usually isn't that hard. If you aren't a programmer, hopefully we can help you as much as we can, so let's get started.

Inspecting Requests, Again

Just like debugging triggers, we'll be using RequestBin to inspect the payloads. This will help you understand what Zapier is sending, making it easier to adjust it to your liking. First, choose any app as a trigger, though it makes sense to choose one you are familiar with, it certainly isn't a requirement. Second, choose Web Hook as your action, POST is probably the most popular, so start there.

In a reversal, instead of Zapier giving you a URL, you'll need to give Zapier a URL. So, give us a RequestBin URL by visiting their homepage and clicking "Create a Request Bin" and copying the Endpoint URL on the screen and paste it into Zapier's Webhook URL field when you are editing your new Zap. Again, they look kind of like this:

https://enfqolxilygu8.x.pipedream.net

Next, you'll need to start configuring your payload. We offer 4 different options at the time of this article: Payload Type, Data, Basic Auth, and Headers. Let's cover a few examples (leaving the rest empty for now):

• Payload Type: json
• Datahello|world

Will result in this webhook (default headers are up top, payload at the bottom):

Content-Type: application/json

{hello: world}

Now, let's say you switch Payload Type to form. Now, you'll get this webhook:

Content-Type: application/x-www-form-urlencoded

hello=world

That certainly isn't the most useful, as the data is static: it never changes. Let's imagine a better example: perhaps we have a Dropbox trigger that pings our web server telling it that there are new files to be copied. We'd want to know about the new files, so maybe we'd do something like this:

• Payload Type: json
• Data: path_to_file|{{path}}

Now, the {{path}} is done via dragging fields from the left to the right in our Zap editor interface. All you have to know right now is that we'll replace it with the real path on the fly, like this:

Content-Type: application/json

{path_to_file: /Important Documents/Business Plan.txt}

Of course, you aren't limited to provided only a single item in the data, plus, you can add headers in the same way like so:

• Payload Type: json
• Data:

path_to_file|{{path}}
file_size|{{size}}
hello|world

• Headers: X-From-Service|Zapier

Which will result in a webhook like this (again, headers are up top):

X-From-Service: Zapier
Content-Type: application/json

{path_to_file: /Important Documents/Business Plan.txt, hello: world, file_size: 822 bytes}

Another option we didn't cover yet is the ability to leave data empty, which tells Zapier to send along all the raw data from the trigger side (which you can always see in step 4). This is a special case that may save you from maintaining a giant list for data mappings.

Pro tip! If you want to get even fancier, you can define children objects with our handy double underscore syntax, for example, this:

root|value
child__extra|value
child__other|value

Will turn into JSON that looks like this:

{root: value, child: {extra: value, other: value}}

Catching the WebHooks

Actually catching and interpreting the webhooks we send is another matter. If you are trying to use webhooks to send payloads to an app we do not support, you may run into insurmountable issues as our data field doesn't support complex structures (for example, lists). In those situations, we would recommend you check out our blog post on using the Developer Platform for processing more complicated payloads.

However, if you are the one writing the code to catch the webhooks you should be able to interpret with only the examples above as a guide. With PHP, the easiest is probably form encoded (Payload Type as form):

?php
echo $_POST['path_to_file'];
echo $_POST['file_size'];
echo $_POST['hello'];
?

But, if you set Payload Type to json, you'll need to decode first:

?php 
$data = json_decode(file_get_contents('php://input'));
echo $data['path_to_file'];
echo $data['file_size'];
echo $data['hello'];
?

We always return a success message for all webhooks - regardless of if there is a Zap behind it that is live or not. This is a technical limitation to enhance availability for a high throughput endpoint - we cannot adjust this!

Triggering Multiple WebHooks At Once

If you have three Zaps with webhook URLs that look like this:

You can combine them into a single URL like this:

Requests sent to this URL will trigger all three webhook URLs at once.

Sending An Array of Objects

The WebHooks by Zapier trigger supports sending more than a single trigger event per webhook request. You can send an array of properly formed JSON objects, and Zapier will trigger the Zap once for each object in the array. This means the Zap will fork and subsequent action steps will run once for each item in the array.

For example, if you POST this payload to a Webhook endpoint:

[
{
    first_name: Alex,
    last_name: Riley,
    age: 27
},
{
    first_name: Sam,
    last_name: Davis,
    age: 28
},
{
    first_name: Jess,
    last_name: Carter,
    age: 29
}
]

Zapier will trigger the actions 3 times, once for every object in the array.

Unflatten Nested Payloads

The Unflatten option in Webhook actions allows you to create nested data from a key with two underscores.

For example, if you have this key and value for data:

If you select "yes" for Unflatten and "Json" for Payload Type, that data will ultimately get sent like this:

{
  parent: {
    child: hello
  }
}

To opt out of this functionality, select "no" for the "Unflatten" option, which will send the data like this:

{
  parent__child: hello
}

Using the Retrieve Poll trigger option

The Retrieve Poll trigger option in the Webhook by Zapier app will let you query a REST API endpoint on the Internet and retrieve data being returned.

This trigger is one that only supports basic authentication - should you need to create your own polling triggers for APIs that offer advanced forms of authentication, you should check out our blog post on using the Developer Platform for this purpose.

Finally, keep in mind that this trigger is one that uses our deduplication process to manage and keep track of records that we have already processed for you that are being returned from this endpoint. You may wish to familiarize yourself with that process before building any Zaps with this specific trigger.

Add Zapier to Your iPhone, iPad, Mac, and Custom Apps

Over 6,00 apps connect directly to Zapier, so you can copy contacts, appointments, form entries, and more without needing to worry about Webhooks URLs and data formats. But if your favorite apps don't have a Zapier integration, webhooks are often the best workaround to connect any app to Zapier.

Have an iPhone or iPad running iOS 12 or later? Apple's Shortcuts app lets you send data from Siri Shortcuts or many iOS apps to a webhooks URL. You can do something similar with the Mac search tool Alfred to run Zaps from your Mac. Or, in many apps especially self-hosted business web apps, you can use webhooks to connect your app to Zapier.

Learn more in our companion guides:

• Add Zapier to Siri Shortcuts on iPhone and iPad
• Add Zapier to Mac with Alfred
• Add Zapier to any app with our Zapier Webhooks guide