What Triggers and Actions Do Webhooks Support?#

Supported Triggers#

  • Retrieve Poll - Poll a URL and look for new entries.
  • Catch Hook - Wait for a new POST, PUT, or GET to a Zapier URL.

Supported Actions#

  • PUT - Fire off a single PUT request as a form or JSON.
  • POST - Fire off a single POST request as a form or JSON.
  • Custom Request - Fire off a custom request by providing raw details. Very flexible but unforgiving.
  • GET - Fire off a single GET request with optional querystrings.

How to Get Started with Webhooks on Zapier#

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=Bryan&last_name=Helmig&age=27

{
    "first_name": "Bryan",
    "last_name": "Helmig",
    "age": 27
}

<first_name>Bryan</first_name>
<last_name>Helmig</last_name>
<age>27</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!

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://zapier.com/hooks/catch/n/Lx2RH/

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.

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.


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 {{contract_winner__first_name}} 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 just 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 them 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 hurl. If you'd like to use curl, check out this handy field guide.

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":"Bryan","last_name":"Helmig","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 Requestb.in. Requestb.in 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. Just click the "Create a Requestb.in" button on their homepage and copy the link in the top bar, it will look kind of like this (make sure it does not have ?inspect at the end):

http://requestb.in/17e2uvw1

Now, log back into your triggering app's settings and replace the old Zapier webhook URL with the new Requestb.in 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 Requestb.in 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 intepret them properly. You should contact us and send us your Requestb.in findings or, if you are a programmer, you can always try parsing the payload yourself via our Developer Platform.

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 Requestb.in 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 Requestb.in URL by visiting their homepage and clicking "Create a Requestb.in" and copying the URL at the top of the screen (make sure it does not have ?inspect at the end) and paste it into Zapier's Webhook URL field when you are editing your new Zap. Again, they look kind of like this:

http://requestb.in/17e2uvw1

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
  • Data hello|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|

Now, the `` 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|
    file_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 highly recommend investing a little time in our developer platform.

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 multiple static webhooks that have URLs that look like this:

  • https://zapier.com/hooks/catch/433703/zbB61/
  • https://zapier.com/hooks/catch/433703/kzXC4/
  • https://zapier.com/hooks/catch/433703/2Ajjn/

You can combine them into a single URL and we'll trigger all of them for you! For example:

  • https://zapier.com/hooks/catch/433703/zbB61,kzXC4,2Ajjn/

Flattening/Unflattening Payloads#

For the data field in the webhook action, if you have a key like parent__child with a value like hello you can flatten/unflatten like so:

  • flatten for {parent__child: "hello"}
  • unflatten for {parent: {child: "hello"}}
↑ Was this documentation useful? Yes No (Suggest Edits)

Popular Things To Do With Webhooks on Zapier#

Common Problems with Webhooks#

Need to send a nested JSON array in the request data.#

To send a nested JSON array, use the Custom Request action. That will allow more flexibility for the payload.

I Got an Error -2. How Do I Fix This?#

This error usually means there's an extra space before the URL in your webhook. Remove the space and you should be good to go!

Why Is It Always 200 or Success Status?#

For High Availability and High Throughput reasons - we always return a success message when collecting a webhook - regardless of if there is a zap behind the webhook and if it is paused or not. The only way to know if a URL is live is to visit the editor and look at the URL (which never changes for a Zap).

Can I do redirects?#

We cannot 301 or 302 you to a different URL and deliver/retrieve payloads from the new address. Doing so will result in a failure!

Why Do I Receive A "413 Request Entity Too Large" Error Status?#

The maximum webhook size we currently support is 100MB. Any payloads that exceed this limit with receive a 413 status code.

Why do I get a "Connection Failure"?#

This is very common if you have a firewall in place to limit access to your local intranet or company network. Open up your instance to the wider internet to give Zapier and similar services access to your server. Be sure to use good passwords if you can!

How do I fix a SSL Certificate Failure?#

Chances are there are a few reasons why you might be running into an SSL certificate failure:

  1. Using a self-signed certificate. We currently only support SSL certificates issued by public certificate authorities. A free SSL certificate can be obtained from letsencrypt.org. Let’s Encrypt is a free, automated, and open certificate authority provided by the non-profit Internet Security Research Group (ISRG).
  2. Incorrect usage of a www.example.com and example.com certificate on a domain like testing.example.com. The reverse can be the case as well, for example: a *.example.com wildcard certificate for example.com.
  3. Other improper installation of the certificate (missing chain certificates, improper modes, etc...). Use a tool like https://www.ssllabs.com/ssltest/ to test.

Webhook Not Returning Results for next Steps#

Unfortunately, not all apps can send back data in a way that our system can interpret in subsequent steps.

If you're familiar with Python or Javascript, a potential workaround is to do this with a Code step. Please note that the Code app is an advanced feature and we aren't able to help troubleshoot the code if there are errors.

Posting JSON from Web Browser + Access-Control-Allow-Headers in Preflight Response Error#

Specifically, the error:

Request header field Content-Type is not allowed by Access-Control-Allow-Headers in preflight response.

This happens when trying to send data to the Zapier webhooks from inside a web browser and altering the Content-Type header during the process. Because of Cross Browser Security restrictions, your browser will reject these requests. To combat this, do not set a custom Content-Type header in the request.

Nothing Found on Trigger Test Stage#

We have to receive a payload of data when your Zap is actively looking for the new data during the test stage:

So when you see the "Looking for the hook, this might take a sec..." message, make sure you send on a payload of data to your webhook address so we can fetch a sample.

If you are still having some trouble, drop us an email and let us know as much as possible about your planned workflow for this Zap so we can help!

↑ Was this documentation useful? Yes No (Suggest Edits)
Get Help