Notification REST Hooks#

Below is the same pattern as our REST Hooks, but with a twist (and an extra step!). Instead of delivering the payload with each hook, it just delivers a resource URL where the payload resides. This helps us move big requests into a queue with everything else which lets us batch bigger requests. The URL can be one-time use or time sensitive as well.

Your Checklist#

  • enumerate the events you'd like to make available as triggers
  • create a subscribe REST endpoint for hooks. For example: POST /api/hooks
  • when each event happens, loop over and notify each active subscription (or batch events of same type)
  • respect 410 responses on payload delivery and remove subscriptions
  • create a unsubscribe REST endpoint for hooks. For example: DELETE /api/hooks/:id

You need to set the subscrube and unsubscribe REST endpoints under Manage Trigger Settings:

Manage Trigger Settings

Read on for a step by step through the endpoints involved...

Step 1: Subscribe (a call from Zapier to your app)#

POST <subscribe_endpoint> \
    -H Authenticated: Somehow \
    -H Content-Type: application/json \
    -d '{"target_url": "<unique_target_url>",
         "event": "user_created"}'

This endpoint reuses whatever auth standard you have across the rest of your API (IE: Basic Auth, API Key, OAuth2, etc...). We'd send along a unique, auto-generated subscription URL and the event we'd like to subscribe to. These three items would be persisted on your backend (the authenticated user, target_url, and event). A subscription is created when a user turns their Zap on.

If you prefer, you can modify this request to provide additional information (like further filtering or other metadata) via our pre_subscribe scripting method.

On a successful subscribe, return a 201 status code. You should store data about the hook you just created via the post_subscribe scripting method (return an object like {"id": 1234}). You'll need this data later to unsubscribe, unless you use the subscription URL as the unique identifier, which is uncommon).

Generally, subscription URLs should be unique. Return a 409 status code if this criteria isn't met (IE: there is a uniqueness conflict).

Step 2: Sending Hooks (a call from your app to Zapier)#

POST<unique_target_url> \
    -H Content-Type: application/json \
    -d {"resource_url": "<resources_url>"}

This hook must include a resource_url or we will not perform a followup GET and thus Zaps will not trigger. If you are currently sending an id, but not a resource_url, you can modify the trigger's catch_hook in scripting to add a resource_url key that uses this id.

On a successful hook, we'll return a 200 status code, content is irrelevant.

If Zapier responds with a 410 status code you should immediately remove the subscription to the failing hook (unsubscribe). Additionally, excessive failures (multiple 4xx or 5xx failures) can be handled at your discretion. It is the clients responsibility to resubscribe if needed after failures.

The maximum hook size is 100MB. Any payloads that exceed this limit will see a 413 status code.

Step 3: Consuming (a call from Zapier to your app)#

GET <resources_url> \
    -H Authenticated: Somehow \
    -H Content-Type: application/json

This is an old fashioned REST hit to a standard endpoint, it requires the same authentication as the rest of the API. It can return a list or a single object.

If you don't want to perform this extra step, look at REST Hooks!

Step 4: Unsubscribe (a call from Zapier to your app)#

DELETE <unsubscribe_endpoint> \
    -H Authenticated: Somehow \
    -H Content-Type: application/json \
    -d <content built/omitted in pre_unsubscribe scripting method>

If you've properly stored identification data about the hook (like its unique ID) from the post_subscribe scripting method, you should use our pre_unsubscribe scripting method to formulate the DELETE call. In that call you have access to your previously stored data under thebundle.subscribe_data variable. Unsubscribing occurs when a user turns their Zap off.

Some example code is provided to make this as easy as possible. A heads up: you will need to use that code if you intend to do a DELETE call. You'll be able to access bundle.subscribe_data to build the URL in pre_unsubscribe. The default behavior is slightly different and listed below.

However, the current default does not perform a DELETE. For example, if you omit the pre_unsubscribe function entirely, we will attempt a default unsubscribe call:

POST <unsubscribe_endpoint> \
    -H Content-Type: application/json \
    -d '{"target_url": "<unique_target_url>"}'

On a successful unsubscribe, return a 200 status code, content is irrelevant.

It is worth remembering that the subscription URL should effectively be unique (this could be enforced by your app as well) which also allows us to clean up unrecognized hooks (we also recommend not requiring authentication for such an endpoint).

↑ Was this documentation useful? Yes No