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"            }        }    }}

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:<YOUR_INTEGRATION>: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"}

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}}",         "headers":[            {               "key":"Authorization",               "value.$":"Bearer {{$.zendeskToken}}"            }         ]      }   }}

This can be referenced in a flow. Example:

"GetTicketByID": {    "Type": "Action",    "ActionName": "zis:<YOUR_INTEGRATION>: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.

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