Configuring the Zendesk Trigger Integration

Our Zendesk Trigger integration allows you to manage access to SendSafely packages (e.g. add recipients, remove recipients or delete packages) based on the state of the associated Zendesk ticket.

For example, you may choose to:

• delete a package when a ticket is closed.
• add a user to a package when a new agent is assigned to a ticket.

or some other package action when any other property of the ticket changes.

These package access actions are achieved with a self-hosted AWS Lambda function called by webhook from a Zendesk trigger.  The following actions are supported:

1. Revoke access to packages: Removes all recipients from each SendSafely package belonging to a particular Zendesk ticket, including any contact groups
2. Add user to packages: Adds a user to every SendSafely package belonging to a particular ticket.
3. Add cc'd users to packages: Adds all users cc'd on a ticket to each SendSafely package belonging to that ticket.
4. Add followers to packages:  Adds all followers on a ticket to each SendSafely package belonging to that ticket.
5. Add contact group to packages:  Adds an enterprise or personal contact group to each SendSafely package belonging to a particular ticket.
6. Delete packages: Deletes all the SendSafely packages belonging to a particular ticket. 

The self-hosted AWS Lambda function and is deployed via a CloudFormation template. In Zendesk, you must also configure a webhook event that is invoked by Zendesk triggers. Follow the below steps to configure this integration.

1. Create the AWS Lambda using CloudFormation

Prerequisites

• Prior to beginning this setup please contact [e-mail] for instructions on how to obtain the CloudFormation template file.

• You have installed Node.js from https://nodejs.org/en/. This Lambda function is compatible with Node.js 18.x

• You have permissions within AWS to setup and deploy new resources. Specifically you will need permission to:
  • Create a new Lambda Function 

  • Create a new SNS Topic (Simple Notification Service)

  • Create a new API (API Gateway Service)
  • Create a new AWS Secret (AWS Secrets Manager )
  • Define a custom IAM Role for the Lambda Function 

Step 1a - Create the AWS Lambda using CloudFormation

First, create a stack by logging into your AWS account. Choose us-east-1 as your region. The CloudFormation template must be deployed in us-east-1, as it queries resources from that region. Browse to the CloudFormation console. Choose:  AWS -> CloudFormation -> Create stack -> With new resources (standard)

Under "Step 1: Specify template" select the following options and click next:

• Prepare template: Template is ready
• Template source:  Upload a template file 
• Template file: The YAML obtained from your SendSafely account representative or SendSafely Support 

Step 1b: Specify stack details

Next, name the stack and populate the following mandatory parameters:

• errorReportingEmail: This is the email address to notify when the Dropzone Connector encounters an errors

NOTE: After the stack is created, the address specified in errorReportingEmail (in this example [e-mail]) will receive an email to confirm the SNS subscription. 

Step 1c: Configure stack options

For this step we recommend that you leave the default values and click the "Next" button. CloudFormation will automatically create a new role for the connector that has the minimum permissions needed for it to run correctly. 

Step 1d: Review

Review and acknowledge the required resources and capabilities then click "Create stack"

 

The Stack may take several minutes to create. You can view the status from the CloudFormation > Stacks screen. Once the entire process completes successfully, the stack will have a status of "CREATE_COMPLETE". You can view a complete list of the resources that were created from the "Resources" tab.  This includes the Lambda function and supporting AWS resources.

 

Step 1e: Confirm the SNS subscription for Error Reporting 

The address specified for the errorReportingEmail should have received an email to confirm the SNS subscription. Click the Confirm subscription link to enable the alerts.

Step 1f: Update Secrets Manager

Lastly, click on the SecretsManager link of the Stacks Resources tab in AWS to update the following:

1. sendsafely_api_key = SendSafely API Key
2. sendsafely_api_secret = SendSafely API Secret
3. sendsafely_base_url = SendSafely portal URL (https://yourcompany.sendsafely.com)
4. zendesk_api_token = zendesk API token (see Appendix for instructions)
5. zendesk_api_email = zendesk API token api user
6. zendesk_portal_url = zendesk portal url  (https://yourcompany.zendesk.com)
7. zendesk_webhook_secret = zendesk webhook secret (see Step 2b below)

Once the fields are updated, click Save.

 

Step 1g: Capture Output

Note down the output for the CloudFormation template. The Endpoint URL will be used Step 2a below

2. Create Webhook in Zendesk

Step 2a - Create Webhook

1. In Zendesk Admin Center, navigate to Apps and integrations > Actions and Webhooks > Webhooks.
2. Press "Create webhook".
3. Select "Trigger or automation" and click Next.
4. Enter a Name and Description.
5. For the Endpoint URL, use the output generated by the deployment of the CloudFormation template (see Step 1g above)
6. For Request method, select "POST".
7. For Request format, select "JSON".
8. For Authentication, select None.
9. Press "Create Webhook".

For further reading, see Zendesk article here.

Step 2b - Get Zendesk Webhook Secret

1. Navigate to the "Webhook" you just created above by going to "Admin Center" --> "Apps and Integrations" --> "Webhooks"
2. Select the "Webhook" that was created.
3. On "Details" scroll all the way to the bottom and copy the "Secret Key"
4. That "Secret Key" will be use to populate the `zendesk_webhook_secret` secrets manager entry.

3. Add a Trigger to invoke Webhook

The next step is to add a "Trigger" that will invoke the "Webhook" we just created.

1. Go to Zendesk "Admin Center" and from there go to "Objects and Rules".
2. Then go to "Business rules" and select "Triggers".
3. From there press "Create trigger" button.
4. Enter the "Trigger name" and "Description" of your choice.
5. For "Trigger category" use "Notifications".
6. Under "Conditions" select conditions that are suitable to perform below listed actions.
7. Under "Actions" for Category select "Notify by > Active webhook" and for Value "<select-the-webhook-we-created-before>".
8. Under "Method" you can send details according to your choice. You will need to send details based on the action that you would like to implement. The body should have a ticket_id field. Below are the body for different actions:

a. Revoke access to packages action

        {
            "ticket_id": "{{ticket.id}}",
            "action: : "revoke_access_to_packages"
        }

b. Add user to packages

        {
            "ticket_id": "{{ticket.id}}",
            "action" : "add_user_to_packages"
            "email" : "email-address-of-the-user-you-want-to-add-to-packages"
        }

c. Add CC'd users to packages

        {
            "ticket_id": "{{ticket.id}}",
            "action" : "add_cc_users_to_packages"
        }

d. Add followers to packages

        {
            "ticket_id": "{{ticket.id}}",
            "action" : "add_followers_to_packages"
        }

e. Delete packages

        {
            "ticket_id": "{{ticket.id}}",
            "action" : "delete_packages"
        }

f. Add Contact Group to packages

        {
            "ticket_id": "{{ticket.id}}",
            "action" : "add_contact_group_to_packages"
            "groupId" : "contact-group-id"
        }

9. Press "Create trigger" and select "Active."

Note 1:

The lambda function supports multiple actions with one single trigger. For example, you can pass

        {
           "ticket_id": "{{ticket.id}}",
           "action" : "add_contact_group_to_packages, add_user_to_packages, add_followers_to_packages",
           "groupId" : "contact-group-id",
           "email": "user-email-to-add-to-packages"
        }

or

        {
           "ticket_id": "{{ticket.id}}",
           "action" : ["add_contact_group_to_packages", "add_user_to_packages", "add_followers_to_packages"],
           "groupId" : "contact-group-id",
           "email": "user-email-to-add-to-packages"
        }

This will carry out the actions in the order specified:

1. First will add the specified contact group to the packages.
2. Second will add the specified user to the packages.
3. Third will add followers to the packages.

Note 2:

You can use the same webhook endpoint for all the above mentioned triggers.

 

Appendix

Obtaining a Zendesk API Token

In order to obtain a Zendesk API Token for the connector, you'll need to be logged into Zendesk with admin privileges. In Zendesk, go to Admin > Channels > API > Settings. Under "Token Access" press the "+" button to obtain a new token.

For security purposes, SendSafely recommends regularly rotating API tokens. 

For additional assistance setting up the SendSafely Zendesk Trigger integration, contact [e-mail].