Zendesk Integration Guide

Zendesk is a popular web-based ticketing system.  This guide will show you how you can use Zendesk’s built-in functionality to integrate it with PagerDuty.  This allows you to send notifications to your team even if it’s after hours. The PagerDuty system allows you to define how and when members of your team should be notified.  You can also set up optional email parsing and a two-way integration to allow Zendesk to autoresolve PagerDuty incidents, and to allow PagerDuty to leave internal notes on Zendesk tickets when actions are taken on the corresponding PagerDuty incident. Steps to set up the two-way integration are outlined after the basic Zendesk to PagerDuty integration, below.

If you are having trouble completing the installation, please contact us.

In PagerDuty:

  1. In your account, under the Configuration tab, select Services from the dropdown menu.Home_-_PagerDuty
  2. Click Add New Service.Services_-_PagerDuty1
  3. Enter a name for the service and select an escalation policy.
  4. Start typing ZenDesk under Integration Type to filter your choices.ZenDesk
  5. Click Add Service.
  6. Once the service is created, you’ll be taken to the service page. On this page, you’ll see the Integration email address, which will be needed when you configure Zendesk to send tickets to PagerDuty.

In Zendesk:

Setting up an Email Target:

  1. Click on the Admin cog in the lower left of the Zendesk UI.Zendesk Admin Page
  2. Under SETTINGS click on Extensions.Zendesk Extensions
  3. Click on the Targets tab and then select add target.Add a Zendesk Target
  4. Locate the icon for Email target and click on it.Add Email Target
  5. Fill out the Title, Email Address (of the service), and Subject line.  The subject can use Zendesk placeholders.  The subject is what you will see within your PagerDuty alert.  Note:  The email address is the integration email that you created earlier in PagerDuty.Configure Email Target
  6. Change the Dropdown to Create target and click Submit.

Setting up a Trigger:

  1.  Click on the Admin cog in the lower left of the Zendesk UI.Zendesk Admin Page
  2. Under BUSINESS RULES click on Triggers.Triggers
  3. Click on add trigger.Add a Zendesk Trigger
  4. Enter a Trigger title and adjust the conditions to which you want to trigger a PagerDuty alert.  The below example will trigger a PagerDuty alert any time that a new Zendesk ticket is created, but your conditions may vary.  Under Perform these actions, select Notifications: Notify target and select the target that you created earlier.  Enter a message that you would like to include within the PagerDuty notification.  This field is also customizable with Zendesk placeholders.  Click on Add trigger when you’re done with your configuration.Zendesk Trigger SettingsBelow is the text that we used for the example message:
    A new Zendesk ticket (#{{ticket.id}}) has been created.To review the status of the ticket and add updates, follow the link below:http://{{ticket.url}}             {{ticket.comments_formatted}}

Integration in Action:

Now when you receive a ticket within Zendesk:Zendesk Ticketa corresponding incident will also be triggered within PagerDuty:PagerDuty Incident Has Been Triggered

Setting up email parsing and the two-way integration:

The instructions above will set up Zendesk to send notifications to PagerDuty when a ticket is created, but you can also set up Zendesk to autoresolve PagerDuty incidents, and set up PagerDuty to comment on Zendesk tickets when the corresponding incident is triggered, acked, or resolved. To have Zendesk automatically resolve PagerDuty incidents, you can follow our Zendesk email parsing guide.

To use the two-way integration, you’ll need to have a Heroku account already set up as well. Once you have set up your basic Zendesk integration, email parsing rules, and Heroku account:

  • In PagerDuty, confirm that your email parsing rules extract the ticket_id (as a custom field) and that they match the information that will be sent over from your Zendesk trigger. Your rules may differ slightly, but please note that ticket_id is necessary for the two-way integration, so you’ll need to make sure it’s being sent to PagerDuty from Zendesk, and extracted in your parsing rules. Here is an example:
    parsing rules
  • You will also need to have the tag pd_integration added to new tickets created in your Zendesk account. You can manually add this to each ticket, however, we created a trigger for this example which will both notify PagerDuty as well as add this tag when a new ticket is created.  We have also pointed out here where the ticket_id (Zendesk placeholder: {{ticket.id}}) is defined in the trigger message. The trigger below follows examples earlier in this guide, however, you can customize this message as long as the ticket ID is included in the message and extracted properly.
    Zendesk PD trigger
  • Once you have your rules and triggers in PagerDuty and Zendesk set up, visit the following link and click Deploy to Herokuhttps://github.com/ryanhoskin/pd2zendesk. This will prompt you to create the app in your Heroku account, where you can fill in the env variables: ZENDESK_USERNAME (your Zendesk login email), ZENDESK_API_TOKEN (visit Admin > Channels > API in Zendesk to view/create tokens), ZENDESK_SUBDOMAIN, PAGERDUTY_API_TOKEN (from your API Access page in PagerDuty), and PAGERDUTY_SUBDOMAIN. Once you’ve filled these in, click Deploy. 
    Heroku env
  • When you see the message Your app was successfully deployed, right click View it and copy the link address, or click View it and copy the URL from your browser’s address bar. In your PagerDuty Zendesk service, click +Add a webhook, enter a name for your webhook, and paste the Heroku URL you copied in the Endpoint URL field. Before saving the webhook, add pd2zendesk.php to the end of your url, so that the finished product reads https://[YOUR-HEROKU-APP-NAME].herokuapp.com/pd2zendesk.php. Click Save. You can now test your integration.
    webhook url
  • To test: create a new Zendesk ticket. You can keep the ticket open to see changes automatically update as they happen. Add the pd_integration tag if you haven’t set up your trigger to add this already, and once the tag has been added you should see an internal note on your ticket noting that the ticket has been triggered in PagerDuty, with a link to the incident.
    zendesk_triggered
  • Acknowledge the incident in PagerDuty. You will see an internal note on the Zendesk ticket noting that the PagerDuty incident has been acknowledged.
    zendesk-acknowledged
  • Resolve the incident in PagerDuty. You will see an internal note on the Zendesk ticket noting that the PagerDuty incident has been resolved.Zendesk_-_resolved
  • OPTIONAL: You could customize this integration by adding additional triggers to take different actions on your Zendesk tickets, based on the comment text added by the PagerDuty integration. You should explore the options when creating a Zendesk trigger for a full scope of what’s possible, but here are some ideas:
    • Set ticket status to open, pending, on-hold, or resolved  based on “This ticket has been acknowledged” or “This ticket has been resolved” comment text.
    • Assign the ticket to a specific Zendesk agent based on comment text.
    • Set Zendesk tags or priority based on comment text.

FAQ

Will Zendesk tickets automatically resolve PagerDuty incidents?

Yes, after following our Zendesk email parsing guide.

How do I setup Zendesk to work with multiple PagerDuty services?

In order to use Zendesk with multiple PagerDuty services, you would setup multiple PagerDuty services with Zendesk email targets and triggers specific to each different service.If you run into any problems with the integration, please contact our support team for assistance.

All Our Integration Guides