Extending your first integration: Triggering a ZIS Flow from external events

In the previous tutorials, you have learnt how a ZIS Flow can be triggered by events originated from Zendesk such as "Run X flow when Y happens". This pattern works well for cases where a Zendesk event requires an update to a third-party system. However, if you want to react to events from a third-party system and update Zendesk, you can use ZIS Inbound Webhooks.

Understanding ZIS Inbound Webhooks

The Inbound Webhooks Service in ZIS is responsible for receiving incoming webhook requests from third party systems. If a third party system supports sending HTTP requests with basic authentication, you can use it to trigger a flow.

In this tutorial, you'll make use of ZIS Inbound Webhooks to trigger a flow that adds a user in Zendesk Support. You'll mimic the third party sending the request to the Inbound Webhook URL with a cURL command.

Note: Requests sent to Inbound Webhook URLs created by this service are authenticated using basic authentication. Support for other authentication types will be added in the future.

Prerequisites

This tutorial makes use of a ZIS Connection that is already stored in ZIS. Complete Using ZIS to obtain Zendesk OAuth token first.

Creating and uploading a ZIS Bundle

  1. In your text editor, create create_user_bundle.json file and paste the following code:

    {  "zis_template_version": "2019-10-14",  "name": "Add a user",  "description": "Add a user",  "resources": {    "AddTagJobSpec": {      "type": "ZIS::JobSpec",      "properties": {        "name": "AddUserJobSpec",        "event_source": "foo_system",        "event_type": "user_created",        "flow_name": "zis:<YOUR_INTEGRATION>:flow:AddUserFlow"      }    },    "AddUserFlow": {      "type": "ZIS::Flow",      "properties": {        "name": "AddUserFlow",        "definition": {          "StartAt": "AddUser",          "States": {            "AddUser": {              "Type": "Action",              "ActionName": "zis:<YOUR_INTEGRATION>:action:AddUser",              "Parameters": {                "access_token.$": "$.connections.zendesk.access_token",                "user_name.$": "$.input.user.name",                "email.$": "$.input.user.email",                "role": "agent"              },              "End": true            }          }        }      }    },    "AddUser": {      "type": "ZIS::Action::Http",      "properties": {        "name": "AddUser",        "definition": {          "method": "POST",          "path": "/api/v2/users",          "headers": [            {              "key": "Authorization",              "value.$": "Bearer {{$.access_token}}"            },            {              "key": "Content-Type",              "value": "application/json"            }          ],          "requestBody": {            "user": {              "name.$": "$.user_name",              "email.$": "$.email",              "role.$": "$.role"            }          }        }      }    }  }}

    Make sure to replace <YOUR_INTEGRATION> with your integration name.

  2. Save the file.

  3. With your command line tool, make a cURL request to upload the bundle to ZIS Registry:

    curl \--request POST \--url https://<SUBDOMAIN>.zendesk.com/api/services/zis/registry/<YOUR_INTEGRATION>/bundles \--user '<EMAIL>:<PASSWORD>' \--header 'content-type: application/json' \-d @create_user_bundle.json

    Replace <SUBDOMAIN> with your Zendesk subdomain, <YOUR_INTEGRATION> with your integration name, and <EMAIL> and <ADDRESS> with your basic authentication credentials.

  4. From the command line tool, make the following cURL request to enable the JobSpec in ZIS Registry:

    curl \--request POST \--url "https://<SUBDOMAIN>.zendesk.com/api/services/zis/registry/job_specs/install?job_spec_name=zis:<YOUR_INTEGRATION>:job_spec:TicketStatusChangedJobSpec,zis:<YOUR_INTEGRATION>:job_spec:CommentAddedJobSpec" \--user '<EMAIL>:<PASSWORD>'
  5. Make an API request to create an inbound webhook URL for receiving HTTP requests. The Create Inbound Webhook endpoint requires an OAuth token. You can use the one you have generated earlier, or to set up a new one, see Building your first integration - Part 2: Obtaining an OAuth token".

    curl -X POST \https://<SUBDOMAIN>.zendesk.com/api/services/zis/inbound_webhooks/generic/<YOUR_INTEGRATION> \  -H 'Authorization: Bearer <YOUR_OAUTH_TOKEN>' \  -H 'content-type: application/json' \  -d '{      "event_type": "user_created",      "source_system": "foo_system"  }'

    event_type and source_system in this API call must match the event_type and event_source properties defined in the AddUserJobSpec JobSpec above. Make a note of the path, username, and password from the response. You use it to make a request to trigger your flow.

    {  "id": "01FDXWD57X1X57NXEE8WQ2EAME",  "uuid": "1dea476d-51b8-4d54-b3e6-c7a7ec29378c",  "zendesk_account_id": 123,  "path": "<path>",  "integration": "<integration>",  "source_system": "foo_system",  "event_type": "user_created_event",  "username": "<username>",  "password": "<password>"}

Note: The generated URL is scoped to the account. The URL doesn't change when you change your subdomain. Make sure to generate a new inbound webhook URL after you change your subdomain. The URL scoped to the old subdomain will be removed from the system automatically.

Testing the integration

Test your setup by making a cURL request to the Incoming Webhook URL:

```curl -u '<USERNAME>:<PASSWORD>' \https://<SUBDOMAIN>.zendesk.com/<PATH> \  -d '{"user": {"name": "Pravin Raj", "email": "[email protected]"}}'```Use  <PATH>, <USERNAME>, and <PASSWORD> obtained from the previous step.

The user Pravin Raj should be created in Zendesk.

Next: Building an integration: Incorporating a request to a self-hosted API