Services and Integrations

Create a service and add integrations to begin receiving incident notifications

A technical service reflects a discrete piece of functionality that is wholly owned by one team. One or more technical services combine to deliver customer-facing or business capabilities.
You can add one or multiple tool integrations to each technical service in order to receive events from those tools.

👍

Best Practices

When creating new services, we highly recommend reading our Service Configuration Guide, which includes best practices and common use cases.

Create a New Service

🚧

Required User Permissions

User, Admin, Manager, Global Admin or Account Owner roles can create services.

If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

  1. Navigate to Services Service Directory and click +New Service.
    Name: A technical service reflects a discrete piece of functionality that is wholly owned by one team. One or more technical services combine to deliver customer-facing or business capabilities.

    Example names of technical services

    • Payment Processing
    • Checkout App Server
    • Inventory Database
    • Create Account
    • Account Authentication
    • Search - Suggest

    Enter a Name based on the guidance provided, and a Description. Click Next to proceed.

  2. Assign: Generate or assign an Escalation Policy to this service. Escalation Policies connect services to individual users and/or schedules and they ensure the right people are notified at the right time.

    Select whether you would like to Generate a new Escalation Policy or Select an existing Escalation Policy and select it from the dropdown. If you generate a new new escalation policy, you will be placed as the first-level on-call for the service. You can update the escalation policy at any time after the service is created. Click Next to proceed.

  3. Alert Grouping: Combine similar alerts into a single incident to reduce notification noise and provide more context when responding to incidents.

📘

Note

Alert grouping is only available for accounts on Digital Operations plans or with the Event Intelligence add-on product.

Select from the following options:

  • Intelligent: Select this option to group intelligently, based on alert content and past groups.
  • Content-Based: To group alerts when contents of specified alert fields match, click Create Grouping and select your alert grouping criteria. You may choose to group alerts based on Any or All of the following fields, then select your preferred Field Name.
  • Time-Based: To group for a selected duration, select your preferred duration from the dropdown.
  • Turn Off Alert Grouping: Select this option if you would not like to use alert grouping.
    Click Next to proceed.
  1. Integrations: Alert feeds can come into PagerDuty from a number of sources. We apply our AI to these alerts and can trigger incidents and notify the right people at the right time.

    Select the integration(s) you use to send alerts to this service from the search bar, dropdown or from our most popular integrations list. If you do not want to add an integration, click Create service without an integration at the bottom of the page.
    Click Create Service.

  2. A Service Profile modal will appear. Once you have read more about the service profile, click Got It.

    • If you chose to add integration(s) to your service: You will now be in the service’s Integrations tab. Find your integration in the list and click the to view and copy your Integration Key. You will now need to follow integration guide instructions to complete integration configuration. Once you have completed the integration guide instructions, your service configuration is now complete.
    • If you did not add integrations to the service, no further configuration is necessary.

You can also customize your service to include other attributes such as urgency, acknowledgment timeouts, auto-resolution, response plays, or alerts.

Edit Existing Service Settings

To edit an existing service's settings:

  1. Navigate to Services Service Directory click the name of your desired service.
  2. Click Edit to the right of the service detail or setting you wish to change.
  3. Once you have edited your preferred settings, click Save changes.

Edit a Service's Escalation Policy

  1. Navigate to Services Service Directory click the name of your desired service.
  2. Select the Settings tab and click Edit to the right of Assign and Notify. Under Assign to escalation policy, search and select your preferred escalation policy and then click Save changes.

Add Integrations to an Existing Service

You can add more than one integration on a service, which allows you to represent the actual entities you are monitoring, managing, and operating as services in PagerDuty. Entities can be applications, micro-services in an application’s architecture, or cross-cutting shared infrastructure (such as networks, security, etc.). With integrations consolidated under one service, you will also have proper service-level reporting in our Analytics module.

  1. In our Integrations Directory, search for and select your integration's guide.
  2. Go to Services Service Directory and select a service to add an integration to. Select the Integrations tab and click the +Add another integration link.
  3. Select the integration(s) you use to send alerts to this service from the search bar, dropdown or from our most popular integrations list.
  4. Click Add. Find your integration in the list and click the to the right to view and copy your Integration Key.
  5. Continue with instructions in the integration guide to complete configuration.

👍

Best Practices

For additional tips on how to use multiple integrations to represent your systems, please check out our best practices article here.

For information on how to add extensions to a service, please visit our section on Extensions.

Edit an Existing Integration

To edit an existing integration:

  1. Navigate to Services Service Directory click the name of your desired service select the Integrations tab click the to the right of your desired integration.
  2. You may edit the Integration name, copy or Generate a new integration key.
  3. Click Save changes.

Move an Integration to Another Service

You have the ability to move an integration from one service to another if need be. You can move integrations between as many services as needed, as many times as needed and all incidents tied to that integration will follow.

📘

Note

Your integration key will not change after moving the integration from one service to another.

  1. Navigate to Services Service Directory.
  2. Click the name of the service which contains the integration you would like to move.
  3. Go to the Integrations tab on the service's page and click the to the right of the integration that you wish to move.
  4. On the right side of the screen, click the Move to Another Service button.

🚧

Note

If the settings on the service you are moving an integration to differ from the current service, you'll receive a warning message with the option to proceed or cancel.

  1. Select the Destination Service where you would like the Integration to move to, and click Move Integration.

Delete an Integration From a Service

If an integration is no longer needed, it can be deleted. A deleted integration cannot be recovered. You will need to create a new integration of the same type on the service should you wish to use that integration again.

  1. Navigate to Services Service Directory select your desired service name Integrations tab click the to the right of the integration.
  2. On the next screen, click the Delete Integration button on the right and then click OK when the confirmation dialog appears.

📘

Note

  • If you'd like to temporarily deactivate an integration instead, you can either place the service in maintenance mode, or temporarily move the integration to an inactive service.
  • When an integration is deleted, we do not remove the incidents. There are no changes to the open or resolved incidents.

Disabling and Re-Enabling Services

Disabling a service is a good choice in the following cases:

  • A service is no longer in use and you want to preserve its settings for future use.
  • Preventing incidents from triggering.

Disabling a service is very similar to putting a service in maintenance mode. New incidents will not trigger while a service is in either of these states.

The main difference is that a maintenance window will eventually end and bring a service back online. A disabled service must be manually re-enabled.

Disable a Service

  1. Navigate to the Services Service Directory.
  2. Click on the name of the service you would like to disable.
  3. Click the More dropdown on the right side, click Disable Service and click Disable on the confirmation dialog.

Re-Enable a Service

  1. Navigate to the Services Service Directory.
  2. Click on the name of the service you would like to enable.
  3. Click the More dropdown on the right side, then click Enable Service button and your service will be re-enabled.

Create a Generic Events API Integration

If there is not an out-of-the-box integration for your tool, you can create an Events API integration for as long as your system can make outbound HTTP calls.

🚧

Required User Permissions

Manager**, Admin, Global Admin or Account Owner roles can add integrations.

**Permissions for adding integrations may vary. Please check for notes on requirements in the intro of the Integration Guide.

If you're not sure what role you have, or if you need your permissions adjusted, visit our sections on Checking Your User Role or Changing User Roles.

To add a generic integration:

  1. Follow instructions to add an integration to an existing service, or to create a new service with an integration, and select Events API V2 or Events API V1 on the Integrations page.
  2. Once complete, you will find the Integration Key in Integrations tab by clicking the to the right of the integration. Use this key in your monitoring tool to send events to PagerDuty, which create incidents on your service.

Events API v2

The Events API allows monitoring tools to directly send events in the PD-CEF format. If you are using custom monitoring, you can also use this format to take advantage of PD-CEF's display and workflow features.

You'll be prompted to choose Events API v1 or v2 when you select Use our API directly from the Integration Type menu.

You must have Create alerts and incidents enabled to use Events API v2. When creating a new service, this setting is under Incident Behavior at the bottom of your service configuration screen. When editing an existing incident, the settings can be found in the Integrations tab of your service under Alert and Incident Settings. When an Events API v2 integration type is selected the Create incidents option will be grayed out.

Should I use Events API v1 or v2?

Events API v2 is designed to handle machine-generated monitoring and event data, such as infrastructure monitoring (Nagios, SignalFX, Datadog), application performance monitoring (New Relic, AppDynamics), and external site checks (Pingdom, Wormly). PD-CEF events generate alerts in PagerDuty, which can then be grouped together under PagerDuty incidents.

For human-generated events, tickets, or incidents, such as those from ServiceNow or JIRA, we suggest using the Events API v2, which enables direct, streamlined creation of PagerDuty incidents.

If you are using a custom monitoring tool, library, or script that has not yet been updated to v2, you should select Events API v1.

Create a Vendor Specific Service via API

The easiest way to create a service and integration is in the PagerDuty web UI, however, you can create a service with a vendor-specific integration (i.e. AWS CloudWatch) via the REST API.

You'll need to know the vendor details, which are not shown in the web UI, but can be obtained via the Vendors API. Afterward, you can create a new service or new integration with the details you received from the Vendors API.

Updated 13 days ago



Services and Integrations


Create a service and add integrations to begin receiving incident notifications

Suggested Edits are limited on API Reference Pages

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