Actions in Zendesk Integration Services (ZIS) are wrappers for a REST API request. ZIS provides some built-in actions, but you can also create your own custom actions such as a request to an external endpoint for an external system.

Custom actions are defined as a resource in your ZIS Bundle, then referenced from your ZIS Flow. Data from the flow is passed to the action to perform an HTTP call. This provides a reusable action to any API endpoint such as Slack, JIRA, Shopify, or an endpoint you've created and hosted yourself.

The following example is a custom action definition that posts a simple message to a webhook.site test URL:

"webhook_site.post_message": {    "type": "ZIS::Action::Http",    "properties": {        "name": "webhook_site.post_message",        "definition": {            "method": "POST",            "url.$": "https://webhook.site/{{$.path_name}}",            "requestBody": {                "text.$": "$.message"            },            "queryParams": [                {                    "key": "foo",                    "value": "bar"                },                {                    "key": "baz",                    "value": "qux"                }            ]        }    }}

You use the action’s name value in the above example to reference the action as a step in your flow in ActionName. Example:

"PostTicketCreatedMessageToWebhook_Site": {    "Type": "Action",    "ActionName": "zis:{integration_name}:action:webhook_site.post_message",    "Parameters": {        "path_name": "{{YOUR_WEBHOOK_SITE_PATH}}",        "message.$": "A new ticket has been created with ID {{$.input.ticket_event.ticket.id}}!"    },    "ResultPath": "$",    "Next": "NextState"}

Elements of a custom action

Parameter Type Description Required Supported values
method string The HTTP method of the request Yes GET, HEAD, PUT, POST, DELETE, OPTIONS, PATCH, TRACE
url string The URL of the HTTP request Note: Cannot be used in combination with path Yes Any valid URL
path string The path component of a HTTP request URL. Used as the relative path for a Zendesk based endpoint; the hostname will be added automatically based on your subdomain Note: Cannot be used in combination with url Yes Any valid path
headers array The header values of the HTTP request formatted as an array of objects with key and value properties No Any
queryParams array The query string parameters of the HTTP request formatted as an array of objects with key and value properties No Any
requestBody object The body of the HTTP request No Any

Capturing your action's response in the ResultPath

To use the response from your action, specify a ResultPath. If the HTTP response is in JSON, the payload is available in $.{{YOUR_RESULT_PATH}}. Otherwise, the response is available in $.{{YOUR_RESULT_PATH}}.__httpresponse

In this example, an action searches for a Zendesk ticket with a specific ID:

"zendesk.get_ticket_by_id_action":{   "type":"ZIS::Action::Http",   "properties":{      "name":"zendesk.get_ticket_by_id_action",      "definition":{         "method":"GET",         "path.$":"/api/v2/tickets/{{$.ticket_id}}.json",         "headers":[            {               "key":"Authorization",               "value.$":"Bearer {{$.zendeskToken}}"            }         ]      }   }}

This can be referenced in a flow. Example:

"GetTicketByID": {    "Type": "Action",    "ActionName": "zis:{integration_name}:action:zendesk.get_ticket_by_id_action",    "Parameters": {        "ticket_id.$": "$.ticket_id",        "zendeskToken.$": "$.connections.zendesk.access_token"    },    "ResultPath": "$.get_ticket_by_id_result",    "Next": "UseMyTicketResults"}

In the above example, if the Zendesk API finds and returns a ticket with the corresponding ID, the ticket payload is available to the UseMyTicketResults state in $.get_ticket_by_id_result.

JSON array responses

If the root object of the action's response is a JSON array, you must set ResultPath to a non-root path. For example, ResultPath may be $.my_result but not $.

Example action response with a JSON array as the root object:

[  {    "id": 1,    "name": "John Smith"  },  {    "id": 2,    "name": "Jane Smith"  }]

Failure to set a non-root ResultPath will cause states later in the flow to not be able to resolve metadata, such as $.connections, $.account_id, $.input.

Zendesk actions versus external actions

  • External action definitions must include a url with an absolute path pointing to the external site
  • Zendesk action definitions must use path to specify the relative path to the Zendesk API endpoint. ZIS will automatically calculate the subdomain and host domain (e.g. https://my_subdomain.zendesk.com/)

This is illustrated in the above examples:

  • The first example contains a url with an absolute path pointing to the external site https://webhook.site/...
  • The second example contains a path with a relative path to a Zendesk API endpoint, which ZIS resolves to an absolute path such as https://my_subdomain.zendesk.com/api/v2/tickets/123

Making data accessible to actions in flows

Flows have access to a JSON object which includes the triggering event's payload ($.input), $.account_id, $.subdomain, and $.integration_key. You can add objects to the $. object using the ResultPath of an action, making data from one state available to subsequent states.

Additional information