1. Home
  2. Integrations
  3. Zendesk Integration Guide – VictorOps

Zendesk Integration Guide – VictorOps

Requirements

Versions Supported: N/A (SaaS)

VictorOps Version Required: Standard (Enterprise required for Ack-Back function described in this article)

What you need to know:  This integration makes use of a feature, Outbound Webhooks. To get more information about this feature please reach out to your account executive or the VictorOps support team. 

This guide walks you through the setup process for integrating Zendesk with VictorOps.  Once complete, Zendesk will be able to automatically trigger, acknowledge, and resolve incidents in VictorOps.  Additionally, acknowledgement of the incident on the VictorOps side can trigger a status change to “pending” (or whatever status you desire) in Zendesk.


In VictorOps

From the main timeline select Settings >> Alert Behavior >> Integrations >> Zendesk.

If the integration has not yet been enabled, click the Enable Integration button to generate your configuration values as seen here:

Copy this endpoint URL to your clipboard.  You will need it when configuring Zendesk.

Routing Key:

The routing key that will be used for this integration should be included in the destination URL.  It is essential that you replace what you see here with the actual routing key you intend to use.  Everything after the final forward slash must be replaced with the key you have configured in VictorOps.  For example, assuming a routing_key value of “database”:

………36437/$routing_key    ==>   ……..36437/database

Routing keys in VictorOps can be set up and associated by clicking on Settings >> Alert Behavior >> Route Keys.

For more information on routing keys and best practices, click HERE.


 In Zendesk


Create a target

From your Zendesk portal select the Settings Gear on the left side-menu.

 

Under the Settings section, select Extensions.

 

In the resulting menu, click on add a target.

 

Select the HTTP Target option.

 

Configure the HTTP target with an intuitive name.  Paste in the endpoint URL you copied from VictorOps (Be sure to change the routing_key value to a valid routing key as noted above).  Select a Method of POST and Content type of JSON.  Leave the Basic Authentication box unchecked and the Test target option selected and click Submit.

 

Copy and paste in the following JSON body, and click Submit.

1
2
3
4
5
{
   "message_type":"info",
   "entity_id":"Test alert from Zendesk",
   "state_message":"testing from Zendesk"
}

 

If configured correctly, you should see a 200 success response similar to this.

 

Check your VictorOps timeline for a new event.  This is an INFO message which will not create a new incident in VictorOps, but is intended only to confirm that Zendesk can successfully send events to VictorOps.

 

Finally, click the x to exit the success message.  Change the option to Create target and click Submit.


Configure Alerts to VictorOps

 

In the left side-menu, locate the section for Business Rules and select Triggers.

 

From the Triggers menu select Add trigger.

 

 

Give the trigger an intuitive name and description.  Click Add condition and add the following two conditions:

– Status is New
– Ticket is Created

Note: You may alter these to further filter which conditions will alert VictorOps or to fit your specific work-flow if you do not wish to create a VictorOps incident for every new case.

 

Under the Actions section, click Add Action.  In the first dropdown (left), scroll down to the Notifications sections and select Notify target.  In the second dropdown (right), select the VictorOps target you created earlier.

 

Copy the JSON payload below and paste it into the JSON body box, then click Create.

Critical Alert

1
2
3
4
5
6
7
8
9
10
11
12
{
  "entity_id":"{{ticket.title}}",
  "message_type":"CRITICAL",
  "state_message":"{{ticket.comments_formatted}}",
  "monitoring_tool":"Zendesk",
  "alert_url":"{{ticket.link}}",
  "ticket_id":"{{ticket.id}}",
  "Ticket External I.D.":"{{ticket.external_id}}",
  "Ticket Origin":"{{ticket.via}}",
  "Ticket Status":"{{ticket.status}}",
  "Ticket Priority":"{{ticket.priority}}"
}

 

This trigger will open a new incident in VictorOps.  You will now need to replicate this process to create two more triggers that will send alerts to VictorOps for acknowledgement and recovery events when cases are assigned or closed in Zendesk.  You will reuse the same target created earlier for each new trigger.  Again, you can change the trigger conditions to fit your specific needs.

Acknowledgement Alert

This trigger will send acknowledgement alerts to VictorOps, to ack the incident and stop paging and escalation.

Conditions: Status is Pending.

 

Payload:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "entity_id":"{{ticket.title}}",
  "message_type":"ACKNOWLEDGEMENT",
  "state_message":"{{ticket.comments_formatted}}",
  "monitoring_tool":"Zendesk",
  "alert_url":"{{ticket.link}}",
  "ticket_id":"{{ticket.id}}",
  "Ticket External I.D.":"{{ticket.external_id}}",
  "Ticket Origin":"{{ticket.via}}",
  "Ticket Status":"{{ticket.status}}",
  "Ticket Priority":"{{ticket.priority}}"
}

Resolved Alert

This trigger will send recovery notifications to VictorOps to close out the incident.

Conditions: Status is Closed.

 

Payload:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "entity_id":"{{ticket.title}}",
  "message_type":"RECOVERY",
  "state_message":"{{ticket.comments_formatted}}",
  "monitoring_tool":"Zendesk",
  "alert_url":"{{ticket.link}}",
  "ticket_id":"{{ticket.id}}",
  "Ticket External I.D.":"{{ticket.external_id}}",
  "Ticket Origin":"{{ticket.via}}",
  "Ticket Status":"{{ticket.status}}",
  "Ticket Priority":"{{ticket.priority}}"
}

Ack Back (optional)

Using our Custom Outgoing Webhooks feature, it is possible to have the acknowledgement of a Zendesk incident in VictorOps automatically transition the related Zendesk case to a status of pending (or whatever status you prefer).

First you will need to build the appropriate destination URL for your Zendesk account like so.  Note that certain parts of the URL must be URL encoded in order to function properly, so make sure you follow this structure exactly.

The example built below assumes the following:

  • The Zendesk subdomain is company.zendesk.com
  • The email address of a Zendesk user is johnny.devops@company.com
  • The API token generated by Zendesk is abc123efg456hij789 (Instructions for generating your API key in Zendesk below)

The Destination URL

The structure of the URL is as follows:

https://{email-address}/token:{yourAPI-token}@{your-subdomain}.zendesk.com/api/v2/tickets/${{ALERT.ticket_id}}.json

Given the example data above, the final URL would be the following:

https://johnny.devops%40company.com%2Ftoken:abc123efg456hij789@company.zendesk.com/api/v2/tickets/${{ALERT.ticket_id}}.json

Note the following crucial elements:

  • The “@” symbol in the email address encoded as “%40”
  • The forward slash before the word token is encoded as “%2F”
  • The “@” symbol just before the sub-domain is NOT encoded.
  • The ${{ALERT.ticket_id}} phrase is not altered in any way (This syntax will dynamically insert the Zendesk ticket ID into the URL when the webhook is fired)

Generate the Zendesk API Key.

In the left side-menu, locate the Channels section and click on API.

 

In the Zendesk API menu, on the Settings tab, make sure that Token Access is enabled and then click the “+” button to generate a new key.

 

Give the key a name.  Click the Copy button to copy the key you your clipboard, and click Save.

 

Set Up the Outgoing Webhook

Back in VictorOps, click Settings >> Alert Behavior >>

 

In the Outgoing Webhooks menu, click Add Webhook.

 

For the Event dropdown, choose Incident-Acknowledged.

For the Method, choose PUT.

For the Content Type, choose application/json.

In the To: box, paste the complete destination URL described above.

In the Payload: box, paste the following payload (You can change the status value to your preferred status):

1
2
3
4
5
{
    "ticket":{
       "status": "pending"
    }
}

Finally, give the webhook a brief description and click Save.

 

If you have any questions please contact VictorOps support.

Updated on August 17, 2017

Was this article helpful?

Related Articles