Zendesk Integration Guide | PagerDuty

Zendesk + PagerDuty Integration Benefits

  • PagerDuty for Zendesk facilitates cross-team communication between IT Ops, 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.
  • 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 Targets 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 and Zendesk v1 integration guides are also available.

Integration Walkthrough

Add the Incident Command Console to Zendesk

In PagerDuty

  1. Navigate to Apps & Add ons on the right menu 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 Channels 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. 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 the Get PagerDuty REST API key link to generate a PagerDuty API key.
  4. On the API key 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. Click 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 this knowledge base article.

Edit Access Levels

Once the integration has been completed, if you would like to go back and edit the above permission access levels, go to Extensions & Add-Ons on the right menu find the Zendesk extension under Service Extensions and click Edit on the Zendesk Extension page under Details select your desired Zendesk account Permissions tab.

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. These settings are accessible by going to Extensions & Add-Ons on the right menu find the Zendesk extension under Service Extensions and click Edit on the Zendesk Extension page under Details select your desired Zendesk account 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 the X by each priority level and click Save Changes.
  • To sync notes: Check the Sync Notes checkbox and click Save Changes.

PagerDuty to Zendesk Automation (Optional)

These settings are accessible by going to Extensions & Add-Ons on the right menu find the Zendesk extension under Service Extensions and click Edit on the Zendesk Extension page under Details select your desired Zendesk account Connections tab click the name of the service scroll to PagerDuty → Zendesk.

  1. From each Zendesk status dropdown, select what status the Zendesk ticket should change to when a PagerDuty incident changes status.
  2. 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.
  3. 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.
  4. From the Zendesk ticket type dropdown, select which type of ticket you would like to create when creating them from a PagerDuty incident.
  5. Click Save Changes.

Manage PagerDuty Incidents From Zendesk

After installing the PagerDuty app from the Zendesk Marketplace (step 4 of the Integration Walkthrough), you can trigger and manage incidents right from within Zendesk.

  1. To create an incident, a Zendesk agent can navigate to a Zendesk ticket and then display Apps by clicking the Apps button on the right side of the screen.
  2. The PagerDuty app will appear and prompt agents to log in to their PagerDuty account. Note: If an agent does not have a PagerDuty account, they can still view any incidents that are linked to this incident, but they cannot take any actions to coordinate a response or communicate with stakeholders.
  1. Once the agent has logged in, they can take the following actions from the Zendesk Incident Command Console, on the right hand side of a ticket:
  • Create Incident or Link Incident: Create a new incident link to an existing open incident.
  • Acknowledge: Acknowledge that you are working on the incident and pause any further escalation.
  • Resolve: Resolve the incident.
  • Add Note: Add a note about the incident to communicate with internal teams following it.
  • Add Responders: Add more responders to help with the incident
  • Reassign: Reassign the incident to a different user or to another team’s escalation policy.
  • Run Response Play: Run a response play to mobilize responders, engage stakeholders with status updates, and set up conference bridge collaboration at once. Note: Response Plays are available on our Digital Operations plan and as part of our Modern Incident Response package. Please contact our Sales Team if you would like to upgrade to a plan with this feature.
  • Send a Status Update: Send a status update to internal users that are subscribed to this incident.
  • Unlink incident: Unlink the incident from this Zendesk ticket.
  1. If you are not seeing all of these actions, you may have a limitation based on your permissions. Please contact your team’s admin user or our Support team to assist if you need additional access to these features.
  2. If you would like to condense the information in the Incident Command Console, you can collapse the Detail, Timeline, or Notes headers. You can also click the icon at the bottom of the Console to choose which pieces of information should be displayed.

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 Targets and Triggers.

  1. In the Services menu, select Service Directory.
  • If you are adding your integration to an existing service: Click the name of the service, select the Integrations tab, click Add a new 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 a new integration and continue to the next step.
  1. Enter an Integration Name and select Zendesk API from the Integration Type menu. Click Add Integration.
  2. On the next screen, you will see the Integration Key for this integration. Copy this key and keep it in a safe place for steps below when you create a JSON body.

Configure a Target and Trigger

  1. As a Zendesk admin, navigate to the admin settings and click on the Extensions settings.
  2. Select the option to add target.
  3. Choose the HTTP target > option
  4. On the HTTP Target screen, enter the following:
    Title: Enter a title that will be identifiable when configuring Triggers in later steps.
    Url: Enter the following value: https://events.pagerduty.com/v2/enqueue.
    Method: Select POST.
    Content type: Select JSON.
    Basic Authentication: Leave unchecked.
    Select Create Target from the dropdown.
  1. Click the Submit button to save the target.
  2. While still in the admin settings, select Triggers under Business Rules. 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 Target, and selecting the target created above. Continue on to the next step.
  • If you are creating a new trigger: Click Add trigger and enter a Trigger name and 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 Target, and selecting the target 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 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 take in additional fields in case you want to include additional information.
{
  "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.

Create a Zendesk Ticket From a PagerDuty Incident

In the event that you want to create a Zendesk ticket from a PagerDuty incident, you can do so from the incident details page. You can only create Zendesk tickets from incidents for services that are connected.

  1. Navigate to an incident in PagerDuty, and click the incident Title to open the incident details page.
  2. Select More Actions and then choose the option to create a Zendesk ticket.

View Status Dashboard in Zendesk

📘

Note

The Status Dashboard feature is available on PagerDuty Business and Digital Operations plans. Please contact our Sales Team if you would like to upgrade to a plan including the Status Dashboard feature.

The PagerDuty Status Dashboard is now viewable in Zendesk, allowing support agents to check real-time system health from where they work.

To view your Status Dashboard:

  1. In a Zendesk account with the PagerDuty Zendesk integration configured, click the PagerDuty app at the top right. You will see a dropdown with an overview of your current status.
  2. To see more details on the Status Dashboard in PagerDuty, click View Status Dashboard. If you would like to change the selected status dashboard, click the icon, select your preferred dashboard and then click Save.

FAQ

How do I set the 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 Target/Trigger method. You can submit this as a feature request with our Support team.

Updated about a month ago


Zendesk Integration Guide | PagerDuty


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.