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 a list of JSON objects.

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).

Custom Trigger Fields URL#

This allows you to dynamically define user-friendly labels for data returned by triggers. These labels are shown to users in the Zap editor when setting up Actions.

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 the UI will be more easy to understand.

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