Unlock the hidden power of your apps.

Try Zapier Free!

How to Use Zapier Webhooks

Bryan Helmig
Bryan Helmig / November 24, 2012

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 services will send along multiple records at once in the name of efficiency.

If you are a developer, take a look at our webhook design post!

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>

It is important to be familiar with each, as most services 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 service. After you do that, we should start receiving payloads whenever the service 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.


Debugging Triggers


We do our best to just make webhooks "just work" for you, but we can't predict all the wacky ways services 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 service 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 service. There are a few tools that help you do that (like curl) but we generally recommend a service 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 service 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 service'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 service 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 service 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 service 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: Send as JSON?, Data, Basic Auth, and Headers. Let's cover a few examples (leaving the rest empty for now):

  • Send as JSON?: yes
  • 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 Send as JSON? to no. 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:

  • Send as JSON?: yes
  • 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:

  • Send as JSON?: yes
  • 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 a service 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 (Send as JSON? as no):

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

But, if you set Send as JSON? to yes, 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'];
?>

“Zapier is amazing. Took us 30 seconds to setup an integration that saves us 2 hours of work every day.”

Bryan Harris, founder of Videofruit

Try Zapier Today

Build workflows with your apps.

Try Zapier Free

Connect apps. Automate tasks. Get more done.

Try Zapier Free
Load Comments...

Comments powered by Disqus

Workflow

Take the Work out of Workflow

Zapier is the easiest way to automate powerful workflows with more than 750 apps.