Our Dropzone Connector for Zendesk allows you to integrate your SendSafely Hosted Dropzone with Zendesk. Once configured, the connector updates existing Zendesk tickets with SendSafely secure links for file downloads. The connector uses the Dropzone lookup field (Ticket ID) to associate inbound files with the appropriate ticket in Zendesk. This value can either be entered by the customer at the time of Dropzone file submission, or, more commonly, embedded in the Dropzone URL that is provided to the customer by a Zendesk agent.

Step 1: Create GCP project and upload files to Cloud Shell Editor

Create a new project from the GCP Console. Your support representative will provide you with a ZIP file (gcp-zendesk-connector.zip) containing the function code and the Terraform template. Unzip this file on your local device.

Open the Cloud Shell Editor, then drag and drop the extracted "gcp-zendesk-connector" directory directly into the file explorer pane.

The gcp-zendesk-connector/ directory should appear in the Cloud Shell file explorer. Navigate to the terraform/ directory, either via the file explorer or from the terminal window:

$ cd gcp-zendesk-connector/terraform/

Cloud Shell no longer includes Terraform by default, so install it before continuing:

$ mkdir -p ~/.local/bin
$ TF_VERSION=$(curl -s https://checkpoint-api.hashicorp.com/v1/check/terraform | grep -oP '"current_version":"\K[^"]+')
$ wget -q "https://releases.hashicorp.com/terraform/${TF_VERSION}/terraform_${TF_VERSION}_linux_amd64.zip" -O /tmp/terraform.zip
$ unzip -o /tmp/terraform.zip -d ~/.local/bin
$ chmod +x ~/.local/bin/terraform
$ export PATH="$HOME/.local/bin:$PATH"
$ terraform version

To avoid repeating this on every new Cloud Shell session, save the install into $HOME/.customize_environment, which Cloud Shell runs automatically on startup:

$ cat > $HOME/.customize_environment << 'EOF'
#!/bin/bash
wget -O - https://apt.releases.hashicorp.com/gpg | gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/hashicorp.list
apt update && apt install -y terraform
EOF
$ chmod +x $HOME/.customize_environment

Step 2: Deploy from Terraform Template

Confirm you are in the correct project (the project you created earlier) using the following command:

$ gcloud config get project

To change the project, use:

$ gcloud config set project <PROJECT_ID>

You can use the following command to get a list of the active projects and their Project_ID values:

$ gcloud projects list

Enable the following APIs required by the Dropzone Connector:

$ gcloud services enable \
cloudresourcemanager.googleapis.com \
artifactregistry.googleapis.com \
cloudfunctions.googleapis.com \
cloudbuild.googleapis.com \
eventarc.googleapis.com \
firestore.googleapis.com \
iam.googleapis.com \
logging.googleapis.com \
pubsub.googleapis.com \
run.googleapis.com \
secretmanager.googleapis.com \
storage.googleapis.com \
serviceusage.googleapis.com

Note: Attempting to enable these resources from the terraform template can result in syncing issues.

Create your variables file from the provided example:

$ cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars and set:

• project_id: your GCP project ID
• zendesk_portal_url: the URL of your Zendesk instance
• gcp_dropzone_connector_owner: Email address that will get notifications if errors occur
• gcp_notification_email_address: Email address that will send notifications to submitters

Before initializing Terraform, create a one-time state bucket for this project (this stores Terraform's state only, not your secrets or source code):

$ export PROJECT_ID="your-gcp-project-id"
$ gcloud storage buckets create "gs://${PROJECT_ID}-tfstate" --project="${PROJECT_ID}" --location="us-central1"
$ gcloud storage buckets update "gs://${PROJECT_ID}-tfstate" --versioning

Then initialize the Terraform template from within the /terraform directory, pointing it at your state bucket:

$ terraform init -backend-config="bucket=${PROJECT_ID}-tfstate"

Run plan to ensure there are no errors:

$ terraform plan

Then apply the template (this may take a couple minutes):

$ terraform apply

Run these same init/plan/apply commands for both first deployment and any future update, from any machine — Terraform's state (in your bucket) tracks what's already live and updates in place rather than recreating anything.

If the application completes without error, you will see the function URL (function_uri) outputted to the console (along with some other information).

Step 3: Configure SendGrid Email Service

To use SendGrid to send emails, there are two steps:

1. Create API key
2. Verify control of either a single email address or a domain

Navigate to SendGrid from the GCP Marketplace (see Appendix for more details), using the Search Bar to find the SendGrid Email API.

From the navigation bar in SendGrid (on the left hand side) Settings > API Keys and click on the "Create API Key" button.

You can customize the levels of access of this API key, and we advise the approach of "least privilege", selecting "Restricted Access" and setting the following:

• "Mail Send": Full Access
• "Sender Authentication": Read Access

To verify control of an email address or domain, navigate to Settings > Sender Authentication and select the appropriate option from the Sender Identity panel.

Step 4: Update Secret Manager

During deployment, the following secrets were created with placeholder values:

• "sendsafely_validation_key" - This is the validation key for the SendSafely Dropzone you are deploying the connector for. The Dropzone validation key is located on the Dropzone tab of the SendSafely Edit Profile screen when viewing the profile of the Dropzone User.
• "zendesk_oauth_client_id", "zendesk_oauth_client_secret", "zendesk_oauth_scope" - These authenticate the connector to Zendesk via OAuth. Refer to the "Creating an OAuth client in Zendesk" section in the Appendix for instructions on generating the Client ID and Client Secret. Set "zendesk_oauth_scope" to read write.
• "gcp_sendgrid_api_key" - This is the Sendgrid API key used by the connector. Refer to the Appendix of this article for more information on generating a Sendgrid API key.

You will now need to update them with the correct values. From the sidebar menu, click "Security > Secret Manager".

Click into each individual entry, and select "+NEW VERSION". Add the actual secret value and check "Disable all past versions".

Once all the secrets are updated, move onto the next step (where you update the SendSafely Dropzone that you are using as a connector).

Note: If you are using another email provider or are taking an alternative approach to sending emails, feel free to amend / ignore the "gcp_sendgrid_api_key" secret. If using an alternative email provider, you will need to adjust the "sendEmail.js" module of the connector.

Step 5: Configure Webhook URL in SendSafely

You now need to update the SendSafely dropzone with the Cloud Function webhook URL. You can find this function URL in the Cloud Shell Editor terminal, once deployment of the Terraform template has been completed. You can also find this URL by going to "Cloud Functions" in the Navigation Menu, and clicking on the "zendesk-connector" function.

Within the "Function Details" view, you will see the URL displayed along the top of the screen. Copy this URL to the clipboard.

Log in to your SendSafely portal as either the Dropzone owner or as a SendSafely Admin and navigate to the Dropzone profile. Under Notification Settings, select the "Use a Webhook for notifications" option and paste in the WebhookUrl. You should also make sure that the "Form Input Label" value is set to something intuitive like "Zendesk Ticket Number" or "Case Number".

Step 6: Test the Connector (Final Step)

Once you complete the steps above, you should be able to browse to the Dropzone URL and update any valid ticket. If you have not already done so, we recommend that you create a Zendesk macro for inserting Dropzone links into your tickets (refer to the "Creating a Macro to Zendesk for Inserting the Dropzone Link" section of the Appendix below).

The following diagram depicts the default logic implemented within the connector and shows what actions will result under various circumstances.

If testing the connector fails, double check these common issues:

• Make sure that all settings are populated in Secret Manager
• Verify that the Function or Cloud Run can access Secret Manager:
  • Give Secret Manager Secret Accessor access to the default Compute Engine service account (i.e. <project_number>-compute@developer.gserviceaccount.com).
• Verify that Cloud Run allows unauthenticated invocations of the deployed function
• Verify that Function variables are set (if deployment fails)
• Check the name of the Firestore Database. Use "(default)" as name, as this is what the NodeJS Firestore Client will try to connect to by default.

Appendix

Generating a SendGrid API Key

To generate a SendGrid API key, you will need to access your SendGrid account via the Google Marketplace. From the Google Cloud Navigation Menu, select "Marketplace", and type "SendGrid Email API" into the search bar to return the correct service.

Then click "Manage on Provider" to be taken to your SendGrid dashboard.

From the sidebar menu, select "Settings > API Keys" and click "Create API key". Give the key a name and provide it with "Full Access" then click "Create & View". Copy the API key shown on the next page, which should begin with "SG.XXXXXXXXXX", and update GCP Secret Manager with it.

Creating an OAuth client in Zendesk

Note. You may wish to perform this step with a shared/admin service account rather than one tied to a specific employee, as Zendesk attributes API activity from this client to whoever created it.

1. In the Zendesk Admin Center, navigate to Apps and integrations > APIs > OAuth clients.
2. Click Add OAuth client.
3. Enter the following:
   • Name. SendSafely Dropzone Connector (or similar)
   • Client Kind: Confidential. Required for the connector's server-to-server authentication to work.
   • Redirect URLs. This field isn't used by the connector. If Zendesk requires it to proceed, enter your Zendesk portal URL (e.g., https://yourcompany.zendesk.com) as a placeholder, otherwise leave it blank.
4. Click Save.
5. Copy the Secret immediately, as Zendesk only displays it once. If you navigate away before copying it, you'll need to generate a new one.

Creating a Macro to Zendesk for Inserting the Dropzone Link

In order to make it convenient for agents to send the correct Dropzone link to customers, we recommend creating a custom macro that can be used to automatically insert the Dropzone link into an agent's reply.

The below instructions are for inserting a link into a support ticket. If you wish to insert a Dropzone link into a Messaging or Chat conversation, follow the macro instructions here.

Browse to Admin > Manage > Macros > Add Macro to create a new macro.

Note that the Dropzone URL also allows you to pre-populate the ticket id in the URL so that your customer does not have to know the correct ticket id to use. The {{ticket.id}} placeholder within the Zendesk macro template can be used to automatically insert the correct ticket ID in the URL as demonstrated below.

{% raw %}https://demo.sendsafely.com/dropzone/zendesk/{{ticket.id}}{% endraw %}

NOTE: You must surround the entire Dropzone URL with the {% raw %} and {% endraw %} tags to avoid having Zendesk attempt to pre-populate the ticket id before the ticket has been submitted. If you do not do this, then the macro will not work effectively in cases where the ticket id has not yet been assigned (like when creating a new ticket).

Take care to ensure that the Zendesk Rich Content editor does not incorrectly try to format your macro URL as a hyperlink. When this happens you will see a portion of the macro URL turn blue. If this happens, click the blue text and choose the trash can icon so that the entire URL is black.

Once the macro has been saved, agents will have the option to use the macro from the bottom of the agent console when replying to a ticket.

Clean Up

$ terraform destroy

Some secrets or IAM bindings may not always be fully removed — verify with gcloud secrets list and gcloud iam service-accounts list.