# Zendesk v2 Integration Guide

Configure the legacy Zendesk v2 integration


> **Version No Longer Supported:** Support for Zendesk v2 ended on March 31, 2023. All PagerDuty customers using Zendesk v2 must upgrade to [Zendesk v3](/integrations/zendesk-integration-guide) before it sunsets. There will be no new development on this version of the feature, and bug fixes will be handled case-by-case.

> **HTTP Targets No Longer Supported:** On February 22, 2022 Zendesk deprecated HTTP targets. You can read more about this on [Zendesk's Knowledge Base](https://support.zendesk.com/hc/en-us/articles/4408826284698-Announcing-the-deprecation-of-HTTP-targets-and-conversion-to-webhooks). Please reference our most current [Zendesk v3 integration guide](/integrations/zendesk-integration-guide) to integrate Zendesk and PagerDuty.

## Zendesk + PagerDuty Integration Benefits

- The Zendesk integration uses Extensions, Targets and Triggers to send Zendesk Support Ticket events to PagerDuty, triggering incidents.
- The PagerDuty app for Zendesk retrieves and interacts with the PagerDuty incident from the Zendesk User Interface.

## 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.

## Requirements

- **In PagerDuty**: A base role of Manager or higher is required to configure this integration. If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on [Checking Your User Role](/account-admin/user-roles#check-your-user-role) or [Changing User Roles](/account-admin/user-roles#edit-user-roles).
- **In Zendesk**: An Administrator role or higher is required to install the app and configure extensions and Triggers.

## Version

**This guide is for Zendesk v2, a legacy version.**

> **Looking for a Different Version?:** - The [Zendesk v3 integration](/integrations/zendesk-integration-guide) is the most current version.
>   - Our [Zendesk v1 integration](/integrations/zendesk-v1-integration-guide), a legacy version, is also available.

## Integration Walkthrough

### In PagerDuty

1. In the **Services** menu, select **Service Directory**.
2. - **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 step 3.
   - **If you are creating a new service for your integration**: Please read our documentation in section [Create a Service](/incident-management/services/services-and-integrations#create-a-service) and follow those steps, selecting **Zendesk API** as the **Integration Type** in step 4. Continue with step 4 (below) once you have finished these steps.
3. Enter an **Integration Name** in the format `ZendeskAPI-Service-Name` (e.g., `ZenDeskAPI-Support-Tickets`) and select **Zendesk API** from the **Integration Type** menu. Click **Add Integration**.
4. On the next screen, you will see the **Integration Key** for this integration. Copy this key and keep it in a safe place for future use.

### In Zendesk

1. In the left hand menu, click the Admin  and select **Extensions** under Settings.
2. Click **Add Target** and then **HTTP Target**.

![Add target](/images/kb/b1a17b892f4dc7ed93555ffead7f549c1fba028ce31a2e0339b63c84d8a20889-zendesk-ig-add-target.webp)
*Add target*

![Select HTTP target](/images/kb/aa8061c1be8f2fc94de6c297385f2be03cbc7c24820282d06c7a2aadd4acd93b-zendesk-ig-http-target.webp)
*Select HTTP target*

3. 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 and then click the **Submit** button.

4. Next, navigate back to the Admin  and 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** and modify the **Actions** section by adding an action to **Notify Target** and select the target created in step 3, above. Continue on to step 5.
   - **If you are creating a new trigger**: Click **Add Trigger** and enter a **Trigger name** and **Description** that describes its desired functionality. Configure your preferred **Conditions** that will determine when you would like Zendesk to send an event to PagerDuty. Next, in the **Actions** section, add an action to **Notify Target** and select the target created in step 3, above. Continue on to step 5.

5. 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 (depending on how you are integrating, this key was generated in step 2 of **Integrating With Global Event Routing**, or step 4 of **Integrating With a PagerDuty Service**, above).
   - 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"
}
```

After configuring the JSON body, click **Create**.

6. Next, navigate to the [Zendesk App Marketplace](https://www.zendesk.com/apps/directory/), search for PagerDuty and install the PagerDuty app.
7. Once you've installed the app, navigate back to your Zendesk account, click **+Add** in the upper left corner and select **Ticket**. On the new ticket, click the **Apps** button on the upper right to display the PagerDuty application. Click **login with PagerDuty** to sign in and access PagerDuty from the Zendesk interface.

![Login with PagerDuty](/images/kb/9b015391b669036c2ac64bd651e1c3371296a714fbcadecbf617ee964712c3da-zendesk-ig-apps-button.webp)
*Login with PagerDuty*

8. There are two ways to test the integration:
   - Modify the ticket created in the last step to meet the Conditions for the Trigger to execute. This should automatically trigger an Event API call once the Priority is set to **URGENT**.
   - You may also create a ticket after signing in to PagerDuty from the Zendesk interface and click the blue **Create Incident** button. On the next screen, select which PagerDuty service you would like to open an incident on.

## FAQ

### I'm using the Business Rules Triggers in Zendesk to trigger notifications to PagerDuty, and incidents are being created, but the PagerDuty App in Zendesk is not loading the incident information on the ticket. What's happening here?

Within the JSON Payload of your Actions from the Business Rules Triggers, ensure that the formatting of the value for `dedup_key` is `Zendesk_[your_Zendesk_subdomain]_{{ticket.id}}`. For example, if the URL to your Zendesk account is `acme.zendesk.com`, the formatting of the the `dedup_key` value should be `Zendesk_acme_{{ticket.id}}`.

### Will PagerDuty create a new Zendesk ticket if there's a non-Zendesk-generated incident on the same service?

No, PagerDuty will not create a new Zendesk Support Ticket if there's an incident that did not originate from Zendesk.

### How does the PagerDuty app in Zendesk look up the incident? What if there are users that shouldn't have access to those incidents?

The PagerDuty app utilizes OAuth to determine the user's permissions to access incidents within PagerDuty. If the user does not have access to a team's incidents, the PagerDuty app will not display that information in the sidebar app.