Triggers#

Overview#

Triggers answer the question: What events can my users listen for with Zapier? They are things like:

  • New Contact (EG: Highrise or Salesforce)
  • New Email (EG: Gmail or IMAP)
  • New Issue (EG: GitHub or Pivotal Tracker)

You can think of a Trigger as a GET or read. It involves Zapier receiving data from your app.

For example, say your app has a "New Ticket Opened" trigger. We will watch for new tickets in a user's account. The data we trigger off of might look like this:

[
  {
    "id": 123456,
    "owner_id": 654,
    "date_created": "Mon, 25 Jun 2012 16:41:54 -0400",
    "description": "Add our app to Zapier"
  }
]

Note: The data in the response must be an array, even for a single data point.

These key/values are available for users to map into the action as they see fit.

What a user sees:

What a developer sees:

See also: Triggers in the CLI

You can define your triggers via your app's dashboard. When you create a new trigger, you'll be prompted with several options. Below we list all complete definitions of what each option is for.

Trigger Options#

Name#

This is a human readable label a user would see when browsing the directory and adding your app. Make it short but descriptive.

Example:
New Ticket Created or New Email with Label

Noun#

This is the object that the trigger is most closely associated with. It will be a noun you used in the Name field. We rely on an accurate noun to generate human-friendly sentences for users.

Example:
"New Ticket Created" would have "Ticket" as the noun. "New Email with Label" would use "Email" or "Labeled Email".

Key#

This is a field only really used internally for both dynamic dropdown and scripting references. Needs to be at least two characters long, start with an alpha, and only contain a-z, A-Z, 0-9 or _.

Example:
new_ticket, or newEmailLabel

Help Text#

A longer description of what this trigger actually watches for.

Example:
Triggers when a new email occurs with a label of your choice.

Demo:
the user will see Name and Help Text like below:

label and help

Important#

Occasionally, you'll have unimportant triggers which are used mostly to drive things like dynamic dropdown, but could be useful to a small subset of users. If you mark a trigger as unimportant, we will hide the trigger behind a link. The user can still pick these if they really want to but it is hidden by default.

Note: if you have no important triggers, we will not hide any of them by default.

Hide#

If you create a trigger solely to be used in a dynamic dropdown and it will never be helpful to users, you can mark it as hidden. We will never show the trigger in the UI and users will not be able to pick it.

This usually comes up with test triggers, where the test trigger is for an endpoint that always returns the same data (a user profile, for instance).

Paging#

When defining a trigger to power a dynamic dropdown you can use the Scripting API to implement paging by relying on bundle.meta.page.

This flag must be set in order to enable paging in the dynamic dropdowns powered by this trigger. If set, the user will see the option in the dropdown to load more choices: “Don’t see your choices? Try loading more than {x}.”

paging

Otherwise, the user will see standard language: “Check {your app} and reload the data”

Note: Paging is not used in normal trigger polling calls.

Polling: URL#

Where in your API can we poll for this trigger? Your URL route can include variables (from authentication fields and trigger fields), as well as query parameters. Query parameters are helpful for telling your API to sort things in reverse-chronological order, a requirement we have.

Important: this endpoint should return JSON encoded list of objects. If the list is nested in an object with meta information we will do our best to find it. If we can't or your API only returns a single object, then you will need to use a _post_poll scripting method to take the response and transform it to a list.

Example:
https://example.com/api/v1/users/{{id}}/contacts.json?sort=desc&on=date_created

A Warning about encoding URL params#

We will not automatically encode any URL variables, so you're responsible for encoding any if they require that. For example, emails might include a + sign, so if you have https://example.com/api/v1/users?email={{email}} you'll want to encode that in your TRIGGER_KEY_pre_poll (or remove it from there and add it to the bundle.request.params), otherwise you'll get a "space" where the + sign is.

A better approach is to not even include it in the URL (it'll be added and encoded automatically in that case).

Optimizing for a fast response#

If you run into errors like Scripting payload too large then your API's response is too big. Here are some tips to prevent that:

Define a KEY_pre_poll scripting method and:

  • When bundle.meta.frontend is true, modify the prepared request to include the relevant parameter that instructs your API to limit to the most recent 3 results. That's all we need when we poll for recent samples in the Editor.
  • When bundle.meta.frontend is not true, modify the prepared request to include the relevant parameter that instructs your API to limit to results for the last 12 hours. We poll every 5 tot 15 minutes, but this allows for some downtime on either side.
  • If the API endpoint is one that may see a lot of results in a short time, try narrowing the above window of 12 hours or in addition add a sensible limit. Be aware that this may cause users to miss tasks, although without they would miss even more if the results are too large to process.

Custom Trigger Result Fields URL#

This allows you to dynamically define user-friendly labels for data returned by triggers as well as fields that may not be found in all live samples. These labels are shown to users in the Zap Editor when they map fields from this trigger to the Edit Template step for actions or searches.

Note: Unlike actions and searches, triggers don't support Custom Trigger Fields for the Edit Template step of the trigger.

Example:
http://api.example.com/v2/fields.json or http://{{account}}.example.com/api/v1/fields.json

If your polling trigger returns:

[
  {
    "id": 1,
    "q_1": "Yes"
  }
]

You can return in the custom fields URL something like:

[
  {
    "label": "Are you happy with your service?",
    "key": "q_1",
    "important": true,
    "type": "unicode"
  }
]

And users will see Are you happy with your service? instead of *Q 1" when they map this field.

Read more about custom field formatting here.

Webhook: Event Name#

A part of our REST Hooks, this lets you namespace the name of event that this trigger identifies with.

Webhook: Static Webhook#

A part of our static webhooks, this simply toggles the ability to receive webhooks and disables polling.

Webhook: Static Webhook Directions#

A part of our static webhooks, when static webhooks are in use this lets you define specialized directions for setup. It also supports Markdown so you can provide links or other specialized HTML formatting.

↑ Was this documentation useful? Yes No
Get Help