Including links in REST-triggered incidents

I’m working on an internal tool to let customer-facing folks trigger incidents for our engineering team from within our chat system, and I’m running into a problem.

The recommended path for human-triggered incidents is to use the REST API, based on the Incident Creation API docs. However, the primary pain point our resolvers have when working on an issue in PagerDuty is that there’s no direct link back to the point in conversation where the incident was triggered, which means there’s missing context.

By triggering an alert event I can provide that context link, but I lose the synchronous workflow; the incident I create is more usable by our resolvers, but I don’t have a handle to it that I can give to the triggering user to let them follow the workflow into PagerDuty.

In an ideal world, I’d like to be able to trigger the incident synchronously, as the REST API does, and provide links that point back to the originating request, as the Events API does, but I can’t find any way to do this.

Absent the ability to create the links directly, I’d also be OK with a solution where I create the incident synchronously and then immediately annotate it with the links via some other API call. So far, based on my API searching, I haven’t found any way to add an alert to a manually triggered incident, and I haven’t found any way to add the nicely-structured links except by attaching them to an alert.

Thanks in advance!

Are you adding webhook extensions to each service to send information back to your tool?

I’m not, but I could. I’m not sure what that would gain me, though.

Hi Jason! Creating webhook extensions in your service allows you to send data about the PagerDuty incident to an endpoint via a POST request. You can learn more in the following Knowledge Base and Developer articles:

Thanks for your prompt responses! I’ve reviewed the docs again, and I understand how the webhooks work, but I’m not sure how they solve my problem.

My goal is to add a link to the PagerDuty incident, so that the responding engineer can click that link when viewing the incident in the PagerDuty dashboard or app, and be taken to the originating point in our customer support chat.

I can add that link by creating the incident using the Events v2 API, but the documentation says this is not the recommended way to create a human-triggered incident, and this forces me into the asynchronous flow.

My only thought on how to apply the webhooks here would be to use the asynchronous workflow, and build some sort of listener using webhooks to close the loop back to the originating user. That’s probably doable, but it would be good to know if there is any other way to attach a link using the recommended synchronous APIs.

Thanks!

Hi Jason,

In an ideal world, I’d like to be able to trigger the incident synchronously, as the REST API does, and provide links that point back to the originating request, as the Events API does, but I can’t find any way to do this.

When you say originating request, I believe we thought you were referring to relaying the PagerDuty incident content back to the customer whom the ticket was created by. In that vain, the webhooks from PagerDuty would be more optimal.

My goal is to add a link to the PagerDuty incident, so that the responding engineer can click that link when viewing the incident in the PagerDuty dashboard or app, and be taken to the originating point in our customer support chat.

If the goal is to include a URL of the chat into the PagerDuty incident’s content for the engineer to access, would it be possible to include the URL to the chat in the incident body at the time of the POST request?

Apologies if there’s more confusion being created! We’re hoping to know what link you are trying to include and where you’re trying to include it though I believe your last quote confirmed you were looking to include the customer chat URL in the PagerDuty incident.

I have a solution that would allow you to update your incident and add an external reference link but it assumes you’re using a webhook for communicating back to your remote tool.

Thanks for the additional information!

The originating request I’m referring to is a record in our chat system where a conversation was flagged to create a new PagerDuty incident. We’ve been able to place the link back to our chat into the description of the incident, but that link is not clickable, and is particularly hard for responders using the PagerDuty mobile app to follow.

We’ve been able to create a clickable link by using the Events v2 API and providing the link in the “links” field, but this is not supported using the synchronous workflow.

If I’m understanding things correctly, I think I see a solution:

  • The synchronous REST API is generally recommended for human-triggered workflows, but it is not what I need here.
  • My approach of using the Events v2 API to create an incident will permit me to create the incident with the properties I want, but I will not get a synchronous response using that API.
  • Instead of waiting for a synchronous response, I should set up a webhook to listen for new incidents. When the webhook is called for the incident, it can use the link in the alert data to locate the original request in our chat, and close the loop by posting a link to the PagerDuty incident.

Based on that:

  1. Does this sound like the approach you would recommend? I’m inferring the webhook portion of the solution based on the statement that I could do this if I had a webhook to update my tool, so I might have guessed wrong.
  2. This solution makes use of the link field in the Events v2 API. Am I correct in assuming that there is no equivalent to this field in the REST Incident Creation API? Is adding that field something the development team might consider as a feature request?
  3. Is there further information on why the Events v2 API recommends that you do not use it for human-triggered events? I always prefer to understand the reasoning behind guidelines that I’m violating, so I know whether I’m setting myself up for maintenance headaches later.

Thanks for your help!

I have a similar use case as @jason.w, and might benefit from your solution. I am using a webhook for my remote tool, but not sure how to use that to create an external reference link. Can you give me some tips?

Shawn - let me gather the API payload and write it up for you. I’ll try to get this tomorrow.

Play around with this some and see if you’re able to update your PagerDuty Incident with an external reference.

Adding an External Reference to a PagerDuty Incident

Request Type: PUT 

URI: https://api.pagerduty.com/incidents/{ID}

Where {ID} is the PagerDuty Incident ID to update

Headers:
* From: email@foo.com
* Accept: application/vnd.pagerduty+json;version=2
* Authorization: Token token=YOUR_TOKEN_HERE

Payload:

* webhook.id = webhook extension ID from PagerDuty service
* external_id = a short reference - MyTool Incident 12345
* external_url = link from PagerDuty Incident to MyTool Incident 12345 (https://myTool.foo.com/INC12345)
* sync = false (there may be other options specific to formal integrations using this)

{
  "incident": {
    "type": "incident_reference",
     "external_references": [{
          "type": "incident_external_reference",
          "webhook": {
            "id": “YOUR WEBHOOK ID HERE“,
            "type": "webhook_reference"
          },
          "sync": false,
          "external_id": “YOUR INCIDENT REFERENCE HERE“,
          "external_url": “LINK TO YOUR TOOL INCIDENT HERE”
        }]
  }
}

Thanks Doug! I’ll give it a shot today. While I’m doing that, is this an official, supported approach? I’m asking only because I didn’t find this in the documentation.

This solution worked beautifully! Thank you, Doug!