Test Triggers#

Note: This guide is for Zapier's legacy web builder. For new integrations, use Zapier Visual Builder and its new Authentication documentation.

A test trigger is a regular trigger with a special responsibility. The test trigger is the trigger Zapier will use to verify the authentication credentials users provide when they first attempt to access your API through Zapier. If your API returns a 2XX status code, we will assume the credentials are valid. Anything else (or an empty response that isn't a 204), and we will assume the credentials are bad.

You can only mark one trigger as the test trigger. A test trigger can be made for any endpoint in your API that:

  1. Requires authentication
  2. Is guaranteed to always return some data (or a 204 for empty responses)

Some examples of good endpoints to use for the test trigger:

  • A url like /ping that is meant solely to test authentication
  • An endpoint that returns a user's profile
  • An endpoint for high-level objects in your API that users are virtually guaranteed to have (i.e. contacts if you are a CRM, tickets if you are a support center)

Setting one up#

In your app, you'll need to choose a trigger that performs a "simple test" when its Polling URL is used to access an endpoint that requires valid authorization/credentials.

If your trigger is intended to be solely used for authentication testing, then you can mark it hidden.

Important make sure that the test trigger doesn't have any "Required" trigger fields (because they'll be empty when we perform the auth test)

Errors#

When your test trigger fails, a message will be displayed to the user like:

The app returned "Email Missing". This usually happens when your Zap is missing a required field or a field value isn't in a recognized format.

We made a request to example.com and received (400) Bad Request.

For "Email Missing" we try to extract the error message from the response body:

  1. We check to see if you send back JSON. If so, we look for a message field, or similar in the JSON object.
  2. We check to see if you send back an XML file (i.e., xml in the Content-Type header). If so, we do a similar lookup for an error message in the body.
  3. We then check to see if you sent back a plain text response(i.e., Content-Type: text/plain). If so, we check that the content is < than 180 characters and use it verbatim.
  4. Finally, we fall back to displaying the response status text or code.

Based on the response status code we then try to add a more general explanation and possible resolution.

Alternatively, you can compose a custom error message by raising an ErrorException in your Scripting. More information in the Available Exceptions section of our docs.

Heads up! This style is only valid for the legacy web builder. Zapier's CLI platform and visual builder expect standard HTTP Errors to be thrown.

Testing#

To select your test trigger, use the button "Manage Trigger Settings":

Scroll down to the bottom of the page, and select the appropriate trigger:

↑ Was this documentation useful? Yes No