Zendesk Integration Guide | PagerDuty

Zendesk + PagerDuty Integration Benefits

  • PagerDuty for Zendesk facilitates cross-team communication between ITOps, DevOps and your customer service teams. Communication silos are broken down, allowing you to mobilize the right resources across teams, in real-time, every time.
  • Installing the PagerDuty app for Zendesk will add an Incident Command Console to your Zendesk account. This console allows PagerDuty to create Zendesk tickets, sync priority and update tickets in real-time.

How it Works

  • Ticket events are sent from Zendesk in JSON format to PagerDuty's Events API based on the Conditions and Actions set during Trigger configuration in Zendesk.
  • These events will turn into incidents in PagerDuty, notifying the configured service’s on-call responders.
  • Agents can manually trigger PagerDuty incidents from a Zendesk ticket, as well as associate Zendesk tickets with PagerDuty incidents.
  • In PagerDuty, you can also configure the Zendesk extension to sync updates bidirectionally.

Requirements

  • In PagerDuty: An Admin base role is required to connect PagerDuty to Zendesk and create a PagerDuty API key. If you do not have this role, please reach out to an Admin or Account Owner within your organization to configure the integration.
  • In Zendesk: A Zendesk administrator will need to generate a Zendesk API key to configure the integration, install the marketplace app, and add any Webhooks or Triggers you choose to set up.

Version

This guide is for Zendesk v3, our most current integration version.

📘

Looking For a Different Version?

Our legacy Zendesk v2 (deprecated) and Zendesk v1 integration guides are also available.

Integration Walkthrough

Add the Incident Command Console to Zendesk

In PagerDuty

  1. Navigate to Integrations Extensions.
  2. Under the Service Extensions menu, click +New Extension, then search and select Zendesk.
  3. Confirm that you want to add the app by clicking Open Zendesk Page on the popup window.
  4. Click the install the PagerDuty app link to open a new window where you can install the Incident Command Console for your users to manage incidents.

In Zendesk

  1. You will be directed to a new tab for the PagerDuty app in the Zendesk marketplace, click Install.
  2. Select your preferred account from the dropdown and then click Install.
  1. You will be directed to your Zendesk account. Click Install again to complete the installation of the app in the Zendesk marketplace.
  1. You will then see PagerDuty listed under Enabled Apps ( Manage Enabled Apps).
  1. While still in the Zendesk admin settings, navigate to Apps and integrations APIs Zendesk API to generate a Zendesk API token. Copy the API token and paste it in a safe place for future use. Note: You will not have access to this key after this screen.
  2. Click Save to continue.

📘

Note

If you have a previous version of the Zendesk app, you can log in to Zendesk and click Manage from the Admin Settings to view the PagerDuty app. Click the PagerDuty icon, and then click Update to update the app.

Configure Bi-Directional Workflows

Authorize the Integration

  1. In PagerDuty, return to the Zendesk Extension page and click Authorize Account to continue configuring the integration.
  2. Enter your Zendesk subdomain, Zendesk user email, and paste the Zendesk API token you just created in Zendesk. Click Authorize.
  3. Click Get PagerDuty REST API key :fa-up-right-from-square to generate a PagerDuty API key.
  4. On the API Access Keys page, click Create New API Key.
  5. Enter a Description (e.g., Zendesk API Key) and click Create Key.
  6. On the next screen, copy the API Key and paste it in a safe place for future use. Note: You will not have access to this key after this screen.
  7. Return to the Zendesk Extension page and enter your PagerDuty email address and the PagerDuty REST API key you just created. Click Save Changes to save the credentials entered.

Add Services

In order to configure workflow rules, or manually create a Zendesk ticket from a PagerDuty incident, you must first map your PagerDuty services to Zendesk.

  1. Select the Connections tab to connect PagerDuty services to Zendesk and build automation rules.
  2. Click Add Service to connect a service in the integration. Select a service from the dropdown and then click Add Service again.
  3. A pop-up will confirm that the service webhooks are correctly configured. If there are any errors, you can click the Check Webhooks button to recreate broken webhooks. Repeat steps 18-19 if you would like to add more services.
  4. Once a Service is added, we predefine some of the automation rules for you. If you would like to change how the integration's rules are configured, you can click the name of the Service to update these rules and follow instructions in the Synced Attributes and PagerDuty to Zendesk Automation sections. Otherwise, the integration configuration is now complete and you may skip to Manage PagerDuty Incidents in Zendesk. If you would like to add more services: Repeat steps 18-21.

Configure Access Levels

In the Permissions tab, you can configure if different groups should have access to all or some actions for the Incident Command Console in the Zendesk platform.

  1. Navigate to the Permissions tab, and choose the abilities that your users should be allowed to perform in the Incident Command Console.

  2. If you’d like to add a new Group Ability, click Add Group Ability, choose the group you’d like to configure, and then select the actions they can take.

  3. Once finished, click Save Changes to save the permissions. Note: These permissions only apply to the Zendesk UI. If you’d like to restrict permissions in the PagerDuty Platform, please refer to our Advanced Permissions article.

Edit Access Levels

You can edit access levels after initial configuration.

  1. In PagerDuty, go to Integrations Extensions.
  2. Find the Zendesk extension under Extension Type and click Edit on the Zendesk Extension page.
  3. Under Authorized accounts, select your desired Zendesk account, then select the Permissions tab.
  4. Make your desired changes and click Save Changes.

Synced Attributes (Optional)

Synced attributes allow you to keep PagerDuty incidents and Zendesk tickets in sync. There are two attributes that sync: Priority and Notes.

To manage synced attributes:

  1. In PagerDuty, go to Integrations Extensions find the Zendesk extension under Extension Type and click Edit on the Zendesk Extension page.
  2. Under Authorized accounts, select your desired Zendesk account, then select the Connections tab click the name of the service.
  • To edit priority syncing: Click the dropdown under PagerDuty priority and select your preferred priority or delete syncing by clicking next to each priority level and click Save Changes.
  • To sync notes: Check the Sync notes checkbox and click Save Changes.

PagerDuty to Zendesk Automation (Optional)

To manage what changes you would like to make to a Zendesk ticket when there is a change to a PagerDuty incident:

  1. In PagerDuty, go to Integrations Extensions find the Zendesk extension under Extension Type and click Edit on the Zendesk Extension page.

  2. Under Authorized accounts, select your desired Zendesk account, then select the Connections tab click the name of the service scroll to the section PagerDuty → Zendesk.

  3. From each Zendesk status dropdown, select what status the Zendesk ticket should change to when a PagerDuty incident changes status.

  4. Check the checkbox to Automatically create Zendesk tickets if you would like Zendesk tickets to be automatically created when there are incidents triggered for this service. If you do not select this option, you can still create a Zendesk ticket manually from an incident.

  5. If you would like Zendesk tickets to be created for incidents with a specific Priority, check the Set incident priority threshold checkbox and select your preferred threshold from the dropdown.

  6. From the Zendesk ticket type dropdown, select which type of ticket you would like to PagerDuty incidents to create.

  7. Click Save Changes.

Automatically Trigger PagerDuty Incidents From Zendesk

There may be circumstances where you want Zendesk to automatically create PagerDuty incidents instead of creating them manually through the Incident Command Console. This can be configured by leveraging Zendesk webhooks and Triggers.

In PagerDuty

  1. Navigate to Services Service Directory.
  • If you are adding your integration to an existing service: Click the name of the service select the Integrations tab Add an Integration and continue to the next step.
  • If you are creating a new service for your integration: Please read our documentation in section Configuring Services and Integrations and follow the steps outlined in the Create a New Service section, then click Add an Integration and continue to the next step.
  1. Search for and select Zendesk API click Add.

  2. On the next screen, click next to Zendesk API to display the integration details click next to Integration Key to copy it to your clipboard. Keep this integration key in a safe place for steps below when you create a JSON body in the next step.

In Zendesk

  1. As a Zendesk admin, navigate to the admin settings and select Apps and Integrations Webhooks.
  2. From the Actions dropdown, choose the Create webhook.
  3. On the Add webhook screen, enter the following:

Field

Value

Name

Enter a name that will be identifiable when configuring Triggers in later steps.

Description (optional)

Enter an optional description for the webhook.

Endpoint URL

Enter https://events.pagerduty.com/v2/enqueue.

Request method

Select POST.

Request format

Select JSON.

Authentication

Select None.

  1. Click Create to save the webhook.
  2. While still in the admin settings, go to Objects and rules Business rules Triggers. Depending on your current configuration, you have the following two options:
  • If you have an existing trigger that you wish to send to PagerDuty: Click the trigger name, then click Add Condition and add Tags, Contains none of the following and the pagerduty tag as pictured below. Then modify the Actions section by clicking Add Action, selecting Notify active webhook, and selecting the webhook created above. Continue on to the next step.
  • If you are creating a new trigger: Click Add trigger and enter a Trigger name and optional Description that describes its desired functionality. Click Add condition and add Tags, Contains none of the following and the pagerduty tag as pictured below. Configure any other preferred Conditions that will determine when you would like Zendesk to send an event to PagerDuty. Next, in the Actions section, add an action by clicking Add action, selecting Notify active webhook, and selecting the webhook created in the steps above. Continue on to the next step.
  1. Next, you will be prompted for a JSON body that takes Zendesk placeholder values. We have provided a sample JSON body that you can use out-of-the-box. If you want to modify the payload in any way, here are some rules to keep in mind:
  • The dedup_key should follow the format of Zendesk_[your_zendesk_subdomain]_{{ticket.id}}. The PagerDuty plugin looks for Zendesk-created incidents with that pattern as a key. Changing this may result in the app plugin not being able to retrieve the associated PagerDuty incident.
  • The routing_key determines which account or service this information should be sent to. Paste your integration key from the earlier step here.
  • The event_action determines what PagerDuty should do once this event is received. You can specify either trigger, acknowledge or resolve here.
  • The payload.custom_details is a custom object that will accept additional fields in case you want to include more information.

Example JSON body

{
  "dedup_key": "Zendesk_[your_zendesk_subdomain]_{{ticket.id}}",
  "routing_key": "[your_integration_key]",
  "event_action": "trigger",
  "payload": {
    "summary": "{{ticket.title}}",
    "source": "{{ticket.via}}",
    "severity": "critical",
    "custom_details": {
      "priority": "{{ticket.priority}}",
      "requester_name": "{{ticket.requester.name}}",
      "status": "{{ticket.status}}",
      "description": "{{ticket.description}}"
    }
  },
  "client_url": "{{ticket.link}}",
  "client": "Zendesk"
}
  1. After configuring the JSON body, click Create.

Zendesk User Guide

Please read our User Guide for more information about using the integration after it has been configured.

FAQ

Can I set the incident priority when automatically creating an incident from Zendesk?

At this time, we aren’t able to set the priority of an incident when creating it through the webhook/Trigger method. You can submit this as a feature request with our Support team.


Did this page help you?