# SDK Reference - triggers

This section enumerates all the possible keys to define a trigger. There are 3 types of triggers available for you to use in Workato:

  • Polling triggers (Check for new events every 5 minutes)
  • Dynamic webhook triggers (Triggers in real time from webhooks. Programmatic subscription and teardown of webhook URLs must be possible in the App)
  • Static webhook triggers (Triggers in real time from webhooks. Webhook URLs are passed from Workato to App by the end user.)

Quick Overview

The triggers key can only be used in both recipes and the debugger console after you have created a successful connection. Triggers are configured by end users of your connector and kick start recipes.

# Structure

    triggers: {

      [Unique_trigger_name]: {
        title: String,

        subtitle: String,

        description: lambda do |input, picklist_label|
          String
        end,

        help: lambda do |input, picklist_label|
          Hash
        end,

        batch: Boolean,

        bulk: Boolean,

        deprecated: Boolean,

        config_fields: Array

        input_fields: lambda do |object_definitions, connection, config_fields|
          Array
        end,

        webhook_key: lambda do |connection, input|
          String
        end,

        webhook_payload_type: String,

        webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
          Hash
        end,

        webhook_unsubscribe: lambda do |webhook_subscribe_output|
          Hash
        end,

        webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
          Hash
        end,

        poll: lambda do |connection, input, closure|
          Hash
        end,

        dedup: lambda do |record|
          String
        end,

        output_fields: lambda do |object_definitions, connection, config_fields|
          Array
        end,

        sample_output: lambda do |connection, input|
          Hash
        end,

        summarize_input: Array,

        summarize_output: Array
      },

      [Another_unique_trigger_name]: {
        ...
      }
    },

# title

Attribute Description
Key title
Type String
Required Optional. Defaults to title built from labeled key.
Description This allows you to define the title of your trigger, which might differ from the name of the key assigned to it - Key = new_updated_object, title = "New/updated object"
Expected Output String
i.e. "New/updated object"
UI reference

TIP

In Workato, we generally advise the following structure for triggers "[Adjective] [Object]" - "New lead" or "New/updated contact" rather than "Lead created".


# subtitle

Attribute Description
Key subtitle
Type String
Required Optional. Defaults to subtitle inferred from connector name and trigger title.
Description This allows you to define the subtitle of your trigger.
Expected Output String
i.e. "Use complex queries to search objects in Percolate"
UI reference

TIP

To make your subtitles meaningful, try to provide more information in here whilst keeping your titles concise. For example, your title could be "New/updated object" whereas your subtitle could be "Trigger off new/updated leads, contacts etc." When users search for a specific triggers, Workato also searches for matches in the subtitle.


# description

Attribute Description
Key description
Type lambda function
Required Optional. Defaults to description inferred from connector name and trigger title.
Description This allows you to define the description of your trigger when viewed in the recipe editor. This can be a static description or a dynamic one based on your needs.
Possible Arguments input - Hash representing user given inputs defined in input_fields
picklist_label - Only applicable for picklists where a user's answer consist of both a picklist label and value. This Hash represents the label for a user's given inputs for picklist fields. See below for use cases.
Expected Output String
i.e. "New or updated <span class='provider'>campaign</span> in <span class='provider'>Percolate</span>" Add the <span> HTML tags to add weight to your description text.
UI reference
Example - description:

For the description block, you have access to two arguments to make your descriptions dynamic. This is useful when you want to change your description based on how a given user has configured the action. These changes can be incredibly useful for your users to ensure they know what this action is doing without having to click and view the action's configuration to understand what it does.

    new_updated_object: {
      description: lambda do |input, picklist_label|
        "New or updated <span class='provider'>#{picklist_label['object'] || 'object'}</span> in " \
        "<span class='provider'>Percolate</span>"
      end,

      config_fields: [
        {
          name: 'object',
          control_type: 'select',
          pick_list: 'object_types',
          optional: false
        }
      ]

      # More keys to define the action
    }

In the example above, this action is a generic object action. What this means is that the action is made to allow the user to create multiple types of objects which the user will select later on when he configures the recipe. This is done by the user selecting what object they wants to create. Since we want the description to change to what object he wants to have selected, the description can be changed to the object selected by referencing the picklist_label argument.


# help

Attribute Description
Key help
Type lambda function
Required Optional. No help is displayed otherwise.
Description The help text that is meant to guide your users as to how to configure this trigger. You can also point them to documentation.
Possible Arguments input - Hash representing user given inputs defined in input_fields
picklist_label - Only applicable for picklists where a user's answer consist of both a picklist label and value. This Hash represents the label for a user's given inputs for picklist fields. See below for use cases.
Expected Output Hash or String See below for examples.
UI reference
Example - help:

The output of the help lambda function can either be a simple String or a Hash. Below we go through the two examples:

  • String
    help: lambda do |input, picklist_label|
      'Create an object in Percolate. First, select from a list of ' \
      'objects that we currently support. After selecting your object,' \
      ' dynamic input fields specific to your scope and object selected ' \
      'will be populated.' \
      ' Creating an approval denotes submitting a specified piece of content' \
      ' or campaign for a specific approval workflow.'
    end,
  • Hash
    help: lambda do |input, picklist_label|
      {
        body: "First, filter by the object you want then fill up the input fields " \
        "which appear based on the object you have selected. Amongst other things, " \
        "you’ll be able to search for contacts in your company and cloud recordings from the past. ",
        learn_more_url: "https://docs.workato.com/connectors/zoom/event-actions.html#search-event-details",
        learn_more_text: "Learn more"
      }
    end,


# batch

Attribute Description
Key batch
Type Boolean
Required Optional.
Description This presents a "Batch" tag next to your action to indicate that this action works with multiple records. Normally used in batch triggers or batch create/update/upsert actions where users can pass a list of records.
UI reference

# bulk

Attribute Description
Key bulk
Type Boolean
Required Optional.
Description This presents a "Bulk" tag next to your action to indicate that this action works with a large flat file of records. Normally used bulk create/update/upsert actions where users pass a CSV of records.
UI reference

# deprecated

Attribute Description
Key deprecated
Type Boolean
Required Optional.
Description This presents a "deprecated" tag next to your action to indicate that this action has been deprecated. Recipes which used to use this action will continue to work but future recipes will not be able to search and select this action.
UI reference

TIP

Deprecation is a great way to move users to new actions when changes are not backwards compatible. This gives you more freedom to make your actions more usable or cater for upcoming API changes.


# config_fields

Attribute Description
Key config_fields
Type Array
Required Optional.
Description This key accepts an array of hashes which show up as input fields shown to a user. Config fields are shown to a user before input fields are rendered and can be used to alter what set of input fields are shown to an end user. This is often used in generic object actions where config fields prompt a user to select the object and input fields are rendered based on that selection. Inputs given to config_fields can be referenced by the connector in the input_fields lambda function via an argument. It is also present as an argument in all object_defintions. To know more about how to define config fields in Workato, click here.
Expected Output Array of hashes. Each hash in this array corresponds to a separate config field.
UI reference

TIP

Config fields are powerful tools to introduce dynamic behaviour to your actions. Use them to make your connector easier to use and discover new features. In the example gif above, you can see that the input "Event" actually causes more input fields to render. These input fields are rendered based on the selection of the value "Meeting".


# input_fields

Attribute Description
Key input_fields
Type lambda function
Required True
Description This lambda function allows you to define what input fields should be shown to a user configuring this trigger in the recipe editor. Output of this lambda function should be an array of hashes, where each hash in this array corresponds to a separate input field. To know more about how to define input fields in Workato, click here.
Possible Arguments object_definitions - Allows you to reference an object definitions. Object definitions are stores of these arrays hashes which may be used to represent both input fields or output fields (datapills). These can be referenced by any action or trigger.
connection - Hash representing user given inputs defined in connection.
config_fields - Hash representing user given inputs defined in config_fields, if applicable.
Expected Output Array of hashes. Each hash in this array corresponds to a separate input field.
UI reference

# webhook_key

Attribute Description
Key webhook_key
Type lambda function
Required True if trigger is a static webhook trigger. False otherwise. Should not be used when webhook_subscribe, webhook_unsubscribe is defined.
Description Used in conjunction with webhook_keys which should be present as a root level key in the connector - same level as actions and triggers

Allows you to use any user input from the connection or trigger to build a unique signature for this trigger. This can also be a static string value. When the signature in this lambda function match the signature in the webhook_keys lambda function, webhooks are sent to this trigger. See our Static webhook guide for more details.
Possible Arguments connection - Hash representing user given inputs defined in connection.
input - Hash representing user given inputs defined in input_fields
Expected Output Array of hashes. Each hash in this array corresponds to a separate input field.
Example - webhook_key:

The webhook_key lambda function is specific to a single trigger and the output signature if built from user inputs. On the other hand, the webhook_keys lambda function is tied to the entire connector and the output signature is built from the incoming webhook's attributes like its body, headers, and query parameters. When expecting a match in these two signature, it becomes easy to see how routing is done from incoming webhooks to the proper trigger to create jobs.

    {
      title: "Sample connector",

      webhook_keys: lambda do |params, headers, payload|
        payload['formId']
      end,

      triggers: {
        sample_static_webhook_trigger: {

          input_fields: lambda do |object_definitions, connection, config_fields|
            [
              {
                name: 'formId',
                label: "Form",
                control_type: "select",
                pick_list: "forms",
                hint: "Select the form you want to trigger this recipe off."
              }
            ]
          end,

          webhook_key: lambda do |connection, input|
            input['formId']
          end,
        }
      }
    }

# webhook_payload_type

Attribute Description
Key webhook_payload_type
Type String
Required Optional. Defaults to "parsed"
Description By default, Workato parses incoming webhook payloads using JSON.parse() (opens new window). Setting webhook_payload_type to "raw" allows you to receive the raw webhook payload instead of a JSON parsed one.
Example - webhook_payload_type: - Verifying webhooks or handling XML webhooks

Use webhook_payload_type in two scenarios:

  1. You need to compute a webhook payload signature based on the raw payload. You may do so in the webhook notification lambda before using workato.parse_json to get the parsed json payload.
      webhook_payload_type: "raw",
      
      webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
        original_payload = payload
        client_secret = input['client_secret'] || account_property('hubspot_webhook_client_secret')
        if client_secret.present?
          source_string = client_secret + original_payload
          v1_signature = source_string.encode_sha256.encode_hex
        end
        
        if (client_secret.present? && v1_signature == headers['X-Hubspot-Signature']) || !client_secret.present?
          payload = workato.parse_json(payload).select do |event|
            event['propertyName'] == input['contact_property'] && event['subscriptionType'] == 'contact.propertyChange'
          end

          if payload.length > 0 
            { 
              events: payload,
              headers: headers,
              webhook_validated: client_secret.present? ? true : false
            }
          end
        end
      end,
  1. You are receiving a webhook that is not in JSON format.
      webhook_payload_type: "raw",
      
      webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params, connection, webhook_subscribe_output|
        payload.from_xml
      end,

# webhook_subscribe

Attribute Description
Key webhook_subscribe
Type lambda function
Required True if trigger is a dynamic webhook trigger. False otherwise. Should not be used when webhook_key is defined.
Description This lambda function is used by dynamic webhook triggers to programmatically subscribe to webhooks. This function is invoked when a user starts the recipe using the trigger with this defined. See our Dynamic webhook guide for more details.
Possible Arguments webhook_url - String representing the recipe-specific webhook URL. This should be passed on to the API when creating the webhook subscription.
connection - Hash representing user given inputs defined in connection.
input - Hash representing user given inputs defined in input_fields
recipe_id - Int representing the ID of the recipe in Workato.
Expected Output Hash which is passed onto the webhook_unsubscribe lambda function.

# webhook_unsubscribe

Attribute Description
Key webhook_unsubscribe
Type lambda function
Required True if trigger is a dynamic webhook trigger. False otherwise. Should not be used when webhook_key is defined.
Description This lambda function is used by dynamic webhook triggers to programmatically teardown webhooks subscriptions. This function is invoked when a user stops the recipe using the trigger with this defined. See our Dynamic webhook guide for more details.
Possible Arguments webhook_subscribe_output - Hash representing the output of the webhook_subscribe lambda function.
Expected Output No output necessary.

Note

The webhook_notification lambda does not allow users to call methods or HTTP methods. If webhook payloads are skinny, please add actions that can take the output of the trigger to perform additional HTTP requests.

# webhook_notification

Attribute Description
Key webhook_notification
Type lambda function
Required True if trigger is either a dynamic webhook trigger or a static webhook trigger.
Description This lambda function handles what this trigger should do with a webhook sent to it. You may use this function to do any data manipulation. This lambda function does not allow you to make additional HTTP requests or invoke additional reusable methods
Possible Arguments input - Hash representing user given inputs defined in input_fields
payload - Hash representing the incoming webhook's payload.
extended_input_schema - See below for examples.
extended_output_schema - See below for examples
headers - Hash representing the incoming webhook's headers.
params - Hash representing the incoming webhook's query parameters.
connection - Hash representing user given inputs defined in connection.
webhook_subscribe_output - Hash representing the output of the webhook_subscribe lambda function.
Expected Output Hash which represents the output of a single job.

# poll

Attribute Description
Key poll
Type lambda function
Required True if trigger is a polling trigger.
Description This lambda function handles the how this trigger retrieves new records from an API to create jobs. This function is invoked every poll interval (5 mins by default but configurable on a recipe level).
Possible Arguments connection - Hash representing user given inputs defined in connection.
input - Hash representing user given inputs defined in input_fields
closure - Hash representing the cursor values passed to the poll lambda function from the previous execution of this same function.
extended_input_schema - See below for examples.
extended_output_schema - See below for examples
Expected Output Hash which contains 3 attributes
- Array of records to be turned into jobs
- Boolean flag which tells the trigger to poll again immediately instead of 5 mins later
- Value/Hash which is stored as the closure which will be passed to the next execution of this same function.
See below for examples

TIP

Closure values can be either a simple string/integer or a hash if you need to store multiple values for your cursor.

Example - poll:

The poll block's output should be a hash in the following structure:

    poll: lambda do |connection, input, closure, _eis, _eos|

      # Timestamp which we need to filter records based off.
      updated_since = (closure || input['since']).to_time.utc.iso8601
      request_page_size = 100

      records = get("/records/endpoint").
                  params(
                     # filter for records only updated after this time
                    updated_since: updated_since,
                    page_size: request_page_size
                  )
      # Example JSON response
      # {
      #   data: [
      #     {
      #       "id": "abcd123",
      #       "name": "record1"
      #       ...
      #     },
      #     {
      #       "id": "dcba321",
      #       "name": "record2",
      #       ...
      #     },
      #     ...
      #   ],
      #   total_records: 1000
      # }

      # Derive last updated since timestamp to filter
      next_updated_since = records['data'].last['updated_at'] unless records.blank?

      {
        # Event accepts an array of records. Each record is a new job.
        events: records['data'],
        # Closure value which is passed as closure argument in next poll
        next_poll: next_updated_since,
        # Boolean flag to denote whether we should wait 5 mins to poll or poll immediately.
        # Poll immediately if total records is still more than page size.
        can_poll_more: records['total_records'] >= request_page_size
      }
    end,
Example - poll: - extended_input_schema and extended_output_schema

Extended input and output schema is any schema from object_definitions that is used in your action. This information is often useful when you dynamically generate schema and you want to use it to do data pre- or post-processing. These arguments do not include config_fields.

For example, you may use extended_input_schema to know which inputs are datetimes and should be transformed to Epoch time which is accepted by the target API. In the same fashion, you may use extended_output_schema to take the response and transform Epoch variables into ISO8601 datetimes again.

    create_object: {
      description: lambda do |input, picklist_label|
        "Create a <span class='provider'>#{picklist_label['object'] || 'object'}</span> in " \
        "<span class='provider'>Percolate</span>"
      end,

      config_fields: [
        {
          name: 'object',
          control_type: 'select',
          pick_list: 'object_types',
          optional: false
        }
      ],

      input_fields: lambda do |object_definitions, connection, config_fields|
        object = config_fields['object']
        object_definitions[object].ignored('id')
      end,

     execute: lambda do |connection, input, extended_input_schema, extended_output_schema|
       puts extended_input_schema
       # [
       #   {
       #     "type": "string",
       #     "name": "status",
       #     "control_type": "select",
       #     "label": "Status",
       #     "hint": "Status is required for creating Content",
       #     "pick_list": "post_statuses",
       #     "optional": false
       #   },
       #   ...
       # ]

       puts extended_output_schema
       # [
       #   {
       #     "type": "string",
       #     "name": "id",
       #     "control_type": "text",
       #     "label": "Content ID",
       #     "hint": "The Content ID, Example: <b>post:45565410</b>.",
       #     "optional": true
       #   },
       #   {
       #     "type": "string",
       #     "name": "status",
       #     "control_type": "select",
       #     "label": "Status",
       #     "hint": "Status is required for creating Content",
       #     "pick_list": "post_statuses",
       #     "optional": false
       #   },
       #   ...
       # ]
     end,

     output_fields: lambda do |object_definitions, connection, config_fields|
       object = config_fields['object']
       object_definitions[object]
      end,
    }

# dedup

Attribute Description
Key dedup
Type lambda function
Required True.
Description This lambda function allows you to deduplicate trigger events so you don't trigger off the same events twice. This is done by forming a unique signature string based off attributes of the incoming record.
Possible Arguments record - Hash representing a single record. This is a single index in the events array of a poll lambda function or the Hash output of the webhook_notification lambda function. .
Expected Output String - "#{record['id']}@#{record['created_at']}" or "#{record['id']}@#{record['updated_at']}"

# output_fields

Attribute Description
Key output_fields
Type lambda function
Required True
Description This lambda function allows you to define what output fields (datapills) should be shown to a user configuring this trigger in the recipe editor. The output of this lambda function should be an array of hashes, where each hash in this array corresponds to a separate output field (datapill). To know more about how to define input fields in Workato, click here.
Possible Arguments object_definitions - Allows you to reference an object definitions. Object definitions are stores of these arrays which can represent either input and output fields. These can be referenced by any action or trigger.
connection - Hash representing user given inputs defined in connection.
config_fields - Hash representing user given inputs defined in config_fields, if applicable.
Expected Output Array of hashes. Each hash in this array corresponds to a separate input field.
UI reference

# sample_output

Attribute Description
Key sample_output
Type lambda function
Required False.
Description This lambda function allows you to define a sample output that is displayed next to your output fields (datapills).
Possible Arguments connection - Hash representing user given inputs defined in connection.
input - Hash representing user given inputs defined in input_fields
Expected Output Hash. This hash should be a stubbed output of the execute lambda function.
UI reference

# summarize_input

Attribute Description
Key summarize_input
Type Array
Required False.
Description Use this to summarize your input which contain long lists. Summarizing your input is important to keep the jobs page lightweight so it can load quickly. In general, when your input has lists that are longer than 100 lines, they should be summarized.
Expected Output Array. For example, ['leads'] or ['report.records', 'report.description']

# summarize_output

Attribute Description
Key summarize_output
Type Array
Required False.
Description Use this to summarize your actions output which contain long lists. Summarizing your output is important to keep the jobs page lightweight so it can load quickly. In general, when your output has lists that are longer than 100 lines, they should be summarized.
Expected Output Array. For example, ['leads'] or ['report.records', 'report.description']
UI reference
Example - Summarizing inputs and outputs in job data

When working with large arrays or data, Workato tries to show all the data in the input and output tabs of the job for each action. Sometimes, this can get confusing when we are working with a large numbers of records or large strings. You can use the summarize_input and summarize_output keys to summarize the data in your job input and output tabs to make it more human readable for users of your connector.

    input_fields: lambda do
      [
        {
          name: 'report',
          type: 'object',
          properties: [
            {
              name: 'records',
              type: :array,
              of: :object,
              properties: [
                {
                  name: 'item_name',
                  type: 'string'
                }
              ]
            },
            {
              name: 'description',
              type: 'string'
            },
            {
              name: 'comment',
              type: 'string'
            }
          ],
        }
      ]
    end,

    summarize_input: ['report.records', 'report.description'],