Help

Send webhooks in Zaps

Last updated:

Intro to webhooks

Webhooks are automated messages sent between apps—a type of notification that includes detailed information about new items in apps. If you're on a paid plan, you can send webhooks in Zaps. If you want a Zap to run when it receives data from a webhook, learn how to trigger Zaps from webhooks.

Tip

Learn more about webhooks in this Zapier blog post: What are webhooks?.


1. Add a webhook action

  • In the Zap editor, click the + icon to add a new step.
  • Search for and select Webhooks by Zapier.
  • Click the Choose Action Event dropdown menu. The Webhooks app offers the POST, PUT, and GET methods, which include automatic data parsing.

Use the POST or PUT methods if your use case involves the following:

  • Sending files (file objects cannot be sent via Custom Request)
  • You're not comfortable writing raw JSON or XML and would prefer the Zap to parse the data for you.

The Webhooks app also offers a Custom Request option. That is much more customizable and allows you to type out raw JSON or XML, but is also much less forgiving - unlike the POST, PUT, and GET templates, it does not automatically parse data for you.

Use the Custom Request option if your use case involves the following:

  • The PATCH or DELETE HTTP methods
  • Sending a nested JSON array
  • Sending empty values
  • Extremely customized Headers

When you're done, click Continue.


2. Select the payload type

To make sure the request is sent in the way your app expects, make sure you have selected the proper Payload Type from the dropdown menu.

There are three common serialization formats that you will see listed here: form-encoded, JSON, and XML. Match the Payload Type field to the format your app requires. Below are examples of each, respectively:

Form-encoded:

first_name=Bryan&last_name=Helmig&age=27

JSON:

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

XML:

<first_name>Bryan</first_name>
<last_name>Helmig</last_name>
<age>27</age>

3. Enter the URL to send the request to

In the URL field, enter the URL where your app’s API is able to receive requests.

It's recommended not to add URL parameters in the URL field. Instead, enter URL parameters in the Data fields, and select Form Encoded as the Payload Type.


4. Fill out the data fields

Fill out the Data section. If you’re using a templated request method like PUT, POST, or GET (i.e. not a Custom Request), enter the field key/label on the left, and the field value on the right. You can use the “+” button to insert field values from previous steps as needed.

If you need to add nested values, you can define child objects with the double underscore syntax. An example of how you might enter that into the Data section is below, with the | indicating the split between the left-hand and right-hand fields:

root | value
child__extra | value
child__other | value

That will turn into JSON that looks like this:

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

If you need more detailed nesting, use a Custom Request instead.

If you’re using a Custom Request, type raw JSON (or other formats) directly into the Data field. Zapier will not parse or format this data for you; it will be sent exactly as entered, so use a JSON (or other) validator if you’re not certain of syntax.

Note

If you leave the Data section blank, all fields from the previous step will be sent as the Request Payload. If you see unexpected fields coming in via your request, ensure you have filled in the Data section for your Webhook action.


5. Add headers and authentication

If your app requires specific Headers, add those to the Headers section.

If your app requires authentication, you can also set up Basic authentication (involving just a username and password, or username and API key) via the Basic Auth section.

If your app requires more advanced authentication options, it's recommended to build a dev app on the developer platform instead.


6. Set up your app to catch Zapier requests

If your app does not have an API that’s ready to catch Zapier requests, catching and interpreting the webhooks sent by a Zap can be tricky. If you're trying to use the Webhooks app to send payloads to an app Zapier does not support, which you do not own, you may run into insurmountable issues as Zapier's data field doesn't support complex structures (e.g. lists). In those situations, it's recommended to look into Zapier's developer platform.

However, if you're writing the code to catch the webhooks, you can refer to the examples below as a guide. With PHP, the easiest is likely form-encoded (Payload Type field set to "Form"):

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

This is because if you set the Payload Type field to "JSON", you'll need to decode that JSON first, as shown below:

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

If your Zap isn't sending webhooks after taking these steps, learn how to troubleshoot Zaps not sending webhooks.

Webhook throttling

  • Each users' webhooks are subject to a collective 429 status code rate limit after 10,000 requests in a 5-minute window. This includes subscription webhooks or REST Hooks.
  • Each individual webhook route will return a 429 status code after around 30 requests per second to encourage a smooth delivery of hooks vs. massive bursts. This includes subscription webhooks or REST Hooks.
  • Legacy webhook routes (which end with "/hooks/catch/abc123", instead of "/hooks/catch/1234567/abc123") will return a 429 status code after 1,000 requests received in a 5 minute window (this is per webhook route). This includes subscription webhooks or REST Hooks.
  • During heavy periods of sustained webhook activity, Zapier may return 200 status but still delay the processing of your webhooks by several minutes.
  • If you wish to enforce proper delivery of webhooks - please retry delivery on anything besides a 200 status code from Zapier and use an industry standard exponential backoff interval for retries.

Need More Help?

Contact Support

Tell us about your problem, and we’ll find you a solution or you can email support.
Get Help

Hire an Expert

We have a directory of professionals across the globe who are ready to help.
Find a Zapier Expert

Zapier Community

Connect with other Zapier users and industry professionals to get help crafting the perfect workflow.
Check out the community