Static Webhooks#

Static webhooks are a very simple version of webhooks wherein the user of your service will have to take action to enable a webhook. Usually, this is done copying a url that Zapier provides during the Zap setup process (like https://zapier.com/hooks/catch/123/n/456789/). We would prefer you use REST hooks but that usually requires extra code and a full REST API.

While Static webhooks are very useful for rapid prototyping, we don't generally accept apps for inclusion in the Zapbook that are solely Static webhooks. Users can use our built in Webhook app to do the same things that a purely Static webhook app can do. You should look at REST Hooks as the next step after you've proved the concept privately with Static webhooks.

To get a taste of how static webhooks work, check out our built-in generic webhook service.

Setup the Webhooks#

To get started simply create a new trigger on your app, choosing static webhook as the type. You can follow the Hubspot example to see a detailed walk through of how to do this.

Once defined in your app, static webhook triggers will appear like this to users when they create a Zap:

static webhook user display

Using the Webhooks#

For as long as the Zap exists, requests made to that URL will be associated with your app and the user. That means requests made during the setup process (while the Zap is paused) will still get stored, making it easier for users to debug. However, requests will not trigger any actions until the Zap is turned on.

Also, it is important to know that by default, we do our best to inspect and pull out all relevant information in a request. If you use scripting to further refine the hook data, you'll see it passed in as bundle.cleaned_request. For example, a request might have a cleaned_request similar to:

POST https://zapier.com//hooks/catch/123/n/456789/?hello=world \
    -H Content-Type: application/x-www-form-urlencoded \
    -d 'some_json=%7B%22foo%22%3A%22hooray!%22%7D&some_xml=%3Cbar%3Eyay!%3C%2Fbar%3E'
{
  "queryset": {
    "hello": "world",
  },
  "some_json": {
    "foo": "hooray!"
  },
  "some_xml": {
    "bar": "yay!"
  }
}

Of course, more simplistic examples like straight JSON or XML are handled as you'd expect.

Catching Single Objects vs. Lists#

Some webhooks send single objects, while some are batched as lists of objects for efficiency reasons. Though Zapier supports both, we highly recommend using scripting if you are dealing with batched lists. We do our best via cleaned_request to interpret lists where possible, but if your list is hidden in a subkey, we won't capture it properly.

For example, a generically supported list:

POST https://zapier.com//hooks/catch/123/n/456789/?hello=world \
    -H Content-Type: application/json \
    -d '[{"name":"bryan","age":27},{"name":"mike","age":23}]'

Would result in two triggers...

{
  "name": "bryan",
  "age": 27
}

...and...

{
  "name": "mike",
  "age": 23
}

Notice that the query string hello=world is ignored? That is because we assumed the data list was more important and we didn't want to maim the data contained therein.

Check out an example where we would ignore a subkeyed list:

POST https://zapier.com//hooks/catch/123/n/456789/?hello=world \
    -H Content-Type: application/json \
    -d '{"data":[{"name":"bryan","age":27},{"name":"mike","age":23}]}'

Because the list isn't at the root, by default, we'll interpret this as a single object. That means we'll only trigger once for this object:

{
  "queryset": {
    "hello": "world",
  },
  "some_json": [
    {
      "name": "bryan",
      "age": 27
    },
    {
      "name": "mike",
      "age": 23
    }
  ]
}

This is where you'd need to break out scripting to do some refinement. Check out the examples we provide in the scripting examples.

Testing Webhooks#

Normally, a user will just log back into your service and force an event by performing the action that causes a webhook to be emitted. This can be a little annoying to the user during setup, so alternatively you can send a X-Hook-Test: true and we will never trigger an action for real, we'll just cache the payload for our UI. This means when the user enables webhooks in your app, just send some sample data across.

↑ Was this documentation useful? Yes No
Get Help