PagerDuty Connect

PagerDuty Connect is a streamlined integration workflow allowing your users to easily integrate their accounts on your service with their PagerDuty accounts. The newly integrated account can then send alerts to PagerDuty through the PagerDuty Integration API.

Introduction – The Integration Handshake

In order for your system to send alerts through PagerDuty you will need to use the PagerDuty Integration API. The API uses a GUID to identify the service to route the alerts to. PagerDuty Integration allows your users to authenticate with PagerDuty and select a service for the integration. Once the handshake is complete, the user is redirected back to your system with the correct GUID and extra information required for alerting with the Integration API.

The handshake is described in four steps in the following figure.

1. When on the your website, the user clicks on the “Alert With PagerDuty” button or link.

2. The user is redirected to the PagerDuty site where they are asked to log into their PagerDuty account. The redirect from your system to PagerDuty contains a vendor key and a callback URL.

3. The user will then create a new service in PagerDuty to be used to integrate with your system.

4. The user is then redirected to the callback URL via HTTP GET with all the necessary parameters for triggering, acknowledging, and resolving incidents with the API.

Note: You can try to above example over at http://www.acmemonitoring.com, a mock monitoring service demonstrating the PagerDuty Integration.

Handshake Parameters and URL

Parameter	Description
vendor	A unique identifier for the partner. Please contact support for your vendor key.
callback	The escaped callback URL where the user information will be sent upon completion of the handshake. This uses HTTP GET to sent the parameters

To initiate the handshake use HTTP redirect to point the user’s browser to the following URL:

https://connect.pagerduty.com/connect?vendor={vendor key}&callback={callback URL}

The Integration Button is at the following URL

https://pagerduty.com/wp-content/uploads/integration-guide-assets-v1/pd_connect_button.png

Callback Response

Once the user authenticates themselves with PagerDuty, their browser is redirected back to the Callback URL via HTTP GET with the following parameters.

Parameter	Description
account	The subdomain of the user’s account.
service_key	An API key used for submitting events to the user’s service.
service_name	The name of the service created.
error	Only if the user cancels the integration partially through the process, they are redirected to the callback url with the parameter error=cancelled.

Using the Integration API

To create incidents in PagerDuty, use the PagerDuty Integration API to submit events.  In addition to the parameters required by the PagerDuty Integration API, you’ll need to submit the following parameters as well.

Parameters

Name	Type	Required	Description
vendor	String	Yes	A unique identifier for the partner. Please contact PagerDuty support for your vendor key. This identifier will be used for initiating handshake and submitting events to PagerDuty.
client	String	No	A label that is shown for the link to event source. For example, if no client is provided, the link will be rendered as View at source otherwise, it will be rendered as View at {client}.
client_url	String	No	The link to the event source.

Example

{
  "event_type":"trigger",
  "vendor": "your-vendor-id",
  "description":"Server www15 running low on memory",
  "service_key": "",
  "incident_key":"srv01/HTTP",
  "client": "your-app-name",
  "client_url": "a-link-to-the-event-source"
  "details" : {
    "server_name": "www15",
    "memory_usage": "98%",
    "threshold": "90%"
  } 
}