Slack + PagerDuty Integration Benefits

• Incident response capabilities within Slack:
  • Trigger, acknowledge, escalate and resolve PagerDuty incidents.
  • Run response plays, create incident Slack channels and send status updates.
• In PagerDuty, users can create on-demand Slack channels from the incident details page.
• Updated notification design with more context from monitoring tools, and actions that respect PagerDuty user permissions.
• Slack V2 Next Generation Migration Support
• Multiple Slack Workspace to PagerDuty Account Connections
• Channel Connection Management, PagerDuty Team to Slack Channel Connections and Channel Connection Filtering
• PagerDuty Slack Integration API

Requirements

In PagerDuty:

• Initial Configuration: This integration requires an Admin, Global Admin or Account Owner base role to perform the initial configuration. This includes mapping your PagerDuty account to your Slack workspace.
• Slack Connection Management: Once your PagerDuty account has been mapped to your Slack workspace (see above) Team Managers, Admins and Account Owners can add a Slack channel connection to a PagerDuty service.
• Using the Integration: In order to use the Slack slash command /pd trigger to trigger a PagerDuty incident, you must have a PagerDuty user license. In other words, all Slack users who have mapped their Slack and PagerDuty accounts can trigger incidents from the Slack interface. Other actions, such as acknowledging, resolving, viewing incident details, adding a note, escalating or running a Response Play follow the PagerDuty user permissions for each action.
  • If some employees in your organization do not have PagerDuty licenses, but you would like them to be able to trigger PagerDuty incidents, you can create an incident trigger Slack workflow to enable this action.
• The Slack integration is supported for both US and EU service regions.

In Slack:

• You need to be a workspace admin or owner.

How it Works

• Users can trigger, acknowledge, resolve, escalate, add notes, run Response Plays and send status updates within Slack, which will send events to PagerDuty, resulting in the corresponding incident actions. Users can also create on-demand Slack channels from incidents in PagerDuty or from incident notifications within Slack.
• When a PagerDuty incident is triggered outside of Slack, an event is sent to the mapped Slack workspace, which generates a message with the incident's details in the designated channel. Users can then perform actions (listed above) within Slack, or within PagerDuty, and the actions will be synced bi-directionally.

Please see the PagerDuty Privacy Policy to read more about how we collect, use and disclose your information.

Version

This guide details configuration of the latest Slack V2 Next Generation integration.

👍

Migrate to Slack V2 Next Generation

• Use our migration tool to migrate from Slack V2 to Slack V2 Next Generation.
• End-of-Life: Slack V2 will reach end-of-life on January 31, 2023.

📘

What's the difference between Slack V2 and Slack V2 Next Generation?

• Slack V2 uses a V2 Webhook Extension and comes with standard features.
• Slack V2 Next Generation uses a V3 Webhook Subscription and comes with updated features. Accounts that configured Slack for the first time after August 10, 2021 have access to this version out of the box.
• Slack V2 Next Generation is managed in Slack Connection Management, not at the service level like previous versions.

📘

Looking for Another Version?

The following version is also available:

• Slack V2

Integration Walkthrough

Initial Configuration

1. First, you will map your PagerDuty account to your Slack Workspace. In PagerDuty, navigate to Integrations Extensions. Select the Slack tile at the top.
   • If prompted, click Authorize Integration.
2. On the Slack Workspaces mapping screen, click Connect a new Workspace to connect your PagerDuty account to your Slack workspace. Connecting your PagerDuty account to your Slack workspace ensures that the PagerDuty bot is present and that PagerDuty slash commands can be executed from any Slack channel.
3. On the next screen, you will be asked to authorize the PagerDuty for Slack integration to perform the following:

• Confirm your identity on PagerDuty

• Access and modify information about your channels: In order to send prompts to Slack users to associate their Slack and PagerDuty usernames, the integration needs to obtain user IDs from the associated channel. The modify channels access is only used for the per-incident, on-demand Slack channel feature.

• Add slash commands and add actions to messages (and view related content)

• Access information about your workspace: This allows the integration to access your team’s profile information and it is used for Slack user association. The list of members from the channel endpoint only gives PagerDuty your Slack ID and this allows it to obtain necessary usernames.

• Send messages as [Workspace Name] for Slack: This allows the integration to post to specific channels in your Slack workspace.

• Access your workspace’s profile information: Similar to the above, this allows the integration to access your team’s profile information and it is used for Slack user association. The list of members from the channel endpoint only gives PagerDuty your Slack ID and this allows it to obtain necessary usernames.

• Send messages as you: This is used to post notifications into the selected channel when a PagerDuty incident has been triggered, updated or resolved.

  Click Allow to authorize.

4. On the next screen you have the option to enable or disable the following settings by toggling them to the on or off position:
   • Notify on incident updates when incidents are reassigned:
     • On: When an incident is reassigned to another team, updates and actions for that incident will be disabled in your channel and enabled in the other team's channel.
     • Off: When an incident is reassigned to another team, updates and actions for that incident will continue to be available in your channel, and they will also be enabled in the other team's channel.
   • Create a Slack thread for all incidents:
     • On: After the initial trigger notification, all further incident notifications will be posted in a thread under the trigger notification.
     • Off: All incident notifications will be posted in the main Slack channel.

Once this step is complete, you can then begin connecting PagerDuty services or teams to a specific Slack channel in the next section.

Add a Slack Channel Connection

5. Next, you will add Slack channel connection(s). On the next screen, click Add Connection. Make selections in the following fields based on your preference:

6. Click Add Connection to connect your PagerDuty source to your Slack channel. To add multiple channel connections, repeat steps 4-5 as many times as needed. Once you have finished adding your connections, the Slack integration is now complete.

📘

Private Slack Channels

If you add a connection to a private Slack channel, the PagerDuty app (@pagerduty) will be automatically added to the channel. If the PagerDuty app is thereafter manually removed from that channel, it will cause the automatic deletion of the connection between the PagerDuty service or team and that Slack channel, and no subsequent incident notifications will be received in the channel.

Using the Integration

Linking User Accounts

In order for users to be able to perform PagerDuty actions from within Slack or create new channel connections on the PagerDuty side, users must first link their PagerDuty and Slack user accounts. This user-linking can be performed by each user as soon as the initial configuration has been completed for a given PagerDuty account and Slack workspace and can be initiated from either PagerDuty or Slack. The following describes how to link user accounts from Slack:

1. In a public Slack channel, run the command /pd oncall, then, if prompted, choose the desired PagerDuty account
2. You'll receive a private message prompt in the same Slack channel; click the provided hyperlink to link your accounts
3. You’ll be directed to log into your PagerDuty account (make sure that you select the correct region and correct sign-on method (SSO or not) appropriate to your PagerDuty account); once you’ve completed authentication to the PagerDuty account, your Slack and PagerDuty users have been successfully linked

Available Slash Commands

Once the updated integration has been installed, new slash commands will be available. You can run the following slash commands from any Slack channel that is connected with PagerDuty:

• /pd help: Display a help message with a list of available slash commands.
• /pd trigger: Trigger a new PagerDuty incident within the Slack interface.
• /pd unlink: Unlink your current Slack user from your PagerDuty user.
• /pd invite @[Slack User Name]: Invites the specified Slack user as a responder to your PagerDuty account.
• /pd oncall: View who is on call for a PagerDuty service.
• /pd insights: Configure the PagerDuty Analytics Slack integration to send recurring insights to Slack.

📘

PagerDuty EU

If your PagerDuty account is in the EU service region, you'll need to use /pdeu to run all slash commands instead of /pd.

🚧

Required Permissions

/pd oncall requires channel-specific permissions. You must invite @PagerDuty to private Slack channels in order to use this Slack slash command.

It is not possible to use this command in other direct messages outside of a direct message with @PagerDuty.

Incident Actions

When an incident is triggered, the incident notification message in Slack will display options for the following incident actions:

• Acknowledge: Acknowledge the incident.
• Resolve: Resolve the incident.
• More actions…: Select the dropdown to access the below actions.
  • View Details: View incident details within the PagerDuty web app.
  • Add a Note : Add a note to the incident.
  • Change Priority : Change an incident’s priority.
  • Reassign: Reassign the incident to another user.
  • Add Responder: Add a responder to the incident.
  • Escalate: Escalate the incident to the next on-call responder.
  • View | Create Channel: Create an on-demand Slack channel for the current incident.
  • New Status Update: Create a new status update for the incident.
  • Run a Play: Run a Response Play.
  • Run a Workflow: Run an Incident Workflow.
  • Run an Action: Run an Automation Action.

Create On-Demand Slack Channels

With this integration, PagerDuty users can create on-demand Slack channels from PagerDuty incidents, and from Slack incident notifications. The following features are available:

• You may fully manage the incident using incident actions.
• View all incident updates within the channel.
• Added responders will be automatically added to the channel.
• A dynamic conference bridge will be automatically added to the incident channel.

🚧

User Permissions

• When you click Set Channel you may be prompted to authorize the connection between your PagerDuty and Slack accounts again, as PagerDuty will attempt to create a channel on behalf of your Slack user account.
• You will only be able to view channels that you have permission to access in Slack.
• If you do not have permission in Slack to create channels, you will not be able to create them from a PagerDuty incident’s Set Channel link.
• If your PagerDuty account is connected to multiple Slack workspaces, you will have the option to select which workspace to use.

Create a Slack Channel from a PagerDuty Incident

1. In the PagerDuty web app, navigate to your desired PagerDuty incident and click its Title to view the incident details screen.
2. Click Set Channel to create an incident-specific Slack channel.

3. Select from the following options:
   • Select existing Slack channel for this incident: Search and select an existing Slack channel.
   • Create a new Slack channel for this incident: You may use the auto-populated incident Slack channel title, or enter a new one. You may also select whether you would like the channel to be Public or Private.
   • Click Set Channel.
4. The channel will be automatically created in Slack.

Create a Slack Channel from a Slack Incident Notification

1. In Slack, navigate to your desired ​​PagerDuty incident notification.
2. Click More actions... and select View | Create Channel. The integration will automatically create a Slack channel (which will include a Zoom conference bridge link) for this incident.

Create an Incident Trigger Slack Workflow

Slack workflows can be used to trigger PagerDuty incidents from Slack with pre-configured details such as the associated service and priority. This option is useful for employees who do not have PagerDuty licenses, but still need to be able to trigger PagerDuty incidents in Slack.

1. In your Slack desktop app, click your workspace name dropdown in the top left and select Tools Workflow Builder. Click Create on the right, enter a workflow name, such as Trigger PD incident, and click Next.
2. Click Select next to Shortcut, select your preferred channel under Which channel?, enter a name under Add a short name, such as Trigger PD incident, and then click Next.
3. Next you will create a form for users to enter information about the incident. Click Add Step search for or select Send a form click Add.
4. In the Send a form modal, enter the following information:

5. Click Save.
6. Next, click Add Step search for or select Trigger PagerDuty incident Add.
   • If prompted, sign into your PagerDuty account, click Sign in. Once signed in, the Trigger PagerDuty Incident step will be added to your Slack workflow.
7. Select your preferred Impacted service, optionally select the Assign to user and optionally select your preferred Priority.
8. Under the Title textfield, click Insert a variable and select Response to: “Title” to add the Title form.
9. Click Save.
   If you would like to add an optional message when someone uses this workflow, continue to step 10. If you do not want to add a message, skip to step 11.
10. Send a Message With Workflow (Optional): Click Add Step and click Add next to Send a message. Under Send this message to: select Channel where workflow started. Under Message text enter your preferred message to be sent with the workflow. You have the option to include variables such as Impacted technical service, Incident number, Incident title, and Incident url by clicking Insert a variable under the message form. Click Save.
11. Click Publish in the upper right to publish your workflow.

Use an Incident Trigger Slack Workflow

1. In your Slack desktop app, select a channel with an Incident Trigger Slack Workflow configured click the Shortcuts at the bottom left of your text field select the Trigger PD incident workflow.
2. Enter a Title for the incident and click Submit.

This will create an incident in PagerDuty, and you will also be able to see the incident details in your Slack channel.

Granular Bot Permissions

The Slack integration uses granular bot permissions, as detailed in the Bot Token Scopes table. All channel connections will be affected by granular bot permissions, but new connections will closely follow Slack workspace security settings. Creating channel connections may require users to have additional Slack permissions or admin authorization, as detailed in the Approve App Update section below.

Approve App Update

There are two Slack settings that may impact the app update:

• App Updates require a Slack Admin approval.
• Only Slack Admins or Slack app Managers can create PagerDuty service to Slack channel connections.

If a user does not have the correct Slack user permissions, then a notification will be sent to a Slack admin to approve the connection. If a Slack admin does not approve the new changes, users will not be able to create new Slack channels and PagerDuty service connections. If your Slack account has not restricted these settings, no action is required.

To approve the app update as a Slack Admin:

1. Navigate to the Slack admin portal and search for the PagerDuty app.
2. At the top right of the page, click Approve next to Manage app for entire workspace? and approve PagerDuty app changes.

Bot Token Scopes

Reauthorization

If your Slack integration was configured prior to April 1, 2021, you may need to reauthorize your Slack scopes in order to gain access to new features.

To reauthorize, PagerDuty admins should visit Integrations Extensions Slack Integration. If reauthorization is required, you will see Reauthorize next to the name of your Slack workspace.

After clicking Reauthorize you will be asked to approve the additional scopes and permissions needed for new functionality. Reauthorization will not impact your current functionality or integration configuration.

Migrate to Slack V2 Next Generation

📘

Migration

If you configured your Slack integration (V1 or V2) prior to August 10, 2021, you may migrate to the Slack V2 Next Generation update using the instructions below. If you configured your Slack integration after that date, you will have access to the update out of the box.

The migration tool makes migrating to Slack V2 Next Generation easy, and only needs to be completed once. There are a few things to note prior to migrating from Slack V1 and V2 to Slack V2 Next Generation:

• During migration, incident notifications, updates, and actions will continue to occur in Slack. You may receive duplicate incident notifications during migration.
• After migrating, the ability to create Slack V1 and V2 connections (which use V2 webhooks) will be disabled. This means Terraform and older extension APIs may stop working, you will only be able to use Slack V2 Next Generation connections (which uses V3 webhook subscriptions) going forward.
• After migration, you will be able to manage Slack channel connections on the Slack Connection Management page; you will no longer be able to manage them at the service level.
• Once the migration has started, it cannot be canceled.

🚧

Requirements

• A PagerDuty Account Owner or Admin base role is required to perform the migration. The PagerDuty user performing migration does not require Slack admin access to all Slack workspaces. Each workspace must be authorized separately and each can be connected by a different PagerDuty/Workspace admin as needed. In order for the Start Migration button to appear, the PagerDuty user performing the migration must be linked to a Slack user on one workspace, but does not need to be linked to a user in every workspace that will be migrated.
• All Slack workspaces using existing Slack V1 and V2 extensions must be connected to PagerDuty (steps 1-4 of Initial Configuration) prior to completing migration.
• If your workspaces are already connected, before performing the migration you must also ensure all of your workspaces have been reauthorized. Check to see if any of your workspaces have a Reauthorize button to the right and click the button to perform reauthorization.

1. In PagerDuty, navigate to Integrations Extensions and select the Slack Integration tile at the top of the page.
2. In the first yellow banner at the top of the page, click Start Migration.

3. Follow the migration widget’s steps:

   a. Click Continue to Authorization.
   b. In the Authorization tab, you will see your current Slack connections and webhooks. If you need to add or update your connections, a PagerDuty user with an Admin role or higher and Slack Workspace Admin or higher can perform these actions.
   c. Click Run Migration. The migration will continue automatically, and it will run in the background if the page is left. When the migration is complete, you will receive a notification on this page.
   d. Once migration is complete, you will be able to see how many webhooks successfully migrated under Webhook Migration Status. If any webhooks failed to migrate, you have the option to Re-run Migration. If all webhooks migrated successfully, then the update is complete. If migration continues to fail, and you have double checked that you satisfied all requirements, please contact our Support team for further assistance.

Add Multiple Slack Workspace to PagerDuty Connections

In this version of the integration, you may add multiple workspace connections to multiple PagerDuty accounts.

Follow the Integration Walkthrough instructions for as many workspaces as you need to add to each PagerDuty account.

Slack Connection Management

With Slack V2 Next Generation, users with a Manager, Admin or Account Owner role can manage connections in PagerDuty on the Slack Connection Management page under Integrations Extensions Slack Integration . Note: This version of the Slack integration is no longer managed at the service level.

🚧

Required User Permissions

• PagerDuty Team Managers (see restrictions below), Admins and Account Owners can view, edit and delete Slack channel connections.
• Team managers with a Restricted Access base role will not be able to manage connections for their team. If a Manager doesn't have access to a service or team, they will be view-only and unable to to edit changes.
• Responders will be able to see a view-only state of all the connections.

Add a New Slack Channel Connection

After configuring the integration for the first time, you may wish to connect additional PagerDuty services with Slack channels; you can repeat the steps in the section Add a Slack Channel Connection.

Edit or Remove a Slack Channel Connection

1. Navigate to Integrations Extensions select the Slack Integration tile. Click View to the right of your desired workspace.
2. To edit the connection, click the icon to the right, make any edits necessary and then click Save Connection. To remove the connection, click the to the right, select Remove Connection and confirm by clicking Remove Connection one more time.

Disconnect Workspace

1. Navigate to Integrations Extensions select the Slack Integration tile. Click View to the right of your desired workspace.
2. Under Authorized Workspace, click Disconnect to the right of your workspace’s name. Enter disconnect in the modal and Disconnect.

Note: This action cannot be undone. If you’d like to reconnect your workspace to PagerDuty, please follow the instructions in the section Integration Walkthrough again.

PagerDuty Slack Integration API

Please view our developer documentation for more information about the PagerDuty Slack Integration API.

FAQ

If I am currently using the Slack V1 or V2 integration, can I update to Slack V2 Next Generation?

Expand

Yes, please use the migration tool to update to Slack V2 Next Generation.

Will Slack V1 and Slack V2 extensions stop working during the migration?

Expand

No, incident notifications, updates, and actions will appear in Slack during migration. You may receive duplicate incident notifications during migration.

In order to migrate to Slack V2 Next Generation, does the PagerDuty Admin have to have Slack Admin access to all Slack workspaces currently connected to PagerDuty?

Expand

No, this is not required.

Why is workspace mapping required for Slack V2 Next Generation?

Expand

Workspace mapping connects a PagerDuty account to a Slack workspace. This provides authorization and access to all channels in a workspace and removes the need to authorize connections on a channel by channel, service by service basis.

Can Managers perform the initial setup of a channel/service connection, or access and edit the settings for a connection?

Expand

• Users with a Manager role or higher can create and manage their teams’ connections.
• A PagerDuty users with an Admin role or higher will still need to connect the PagerDuty account to the Slack Workspace first.

Slack V2 Next Generation requires that the user be a responder in PagerDuty. Is there a way to allow non-PagerDuty users to trigger incidents in Slack?

Expand

With this integration, customers can trigger an incident without a PagerDuty license. Please see the section Create an Incident Trigger Slack Workflow for more information.

After migrating, we can no longer make a Slack channel connection from the service page. Is this expected behavior?

Expand

Yes, after migrating to Slack V2 Next Generation, you will not be able to create Slack connections at the service level. Please use the Slack Connection Management page to administer the Slack integration.

I changed my channel from public to private, and now my incidents aren't posting to Slack.

Expand

Please invite the PagerDuty bot (@PagerDuty ) to your Slack channel after you set it to private.

Do I need to install anything else to use slash commands?

Expand

No, slash commands are available out-of-the-box with the Slack V2 Next Generation integration. In order use the /pd trigger command, please make sure that you’ve mapped Slack workspace PagerDuty (step 4 of the Integration Walkthrough). Note: Users must have a PagerDuty license and be signed in to use /pd trigger.

Can I add multiple Slack workspaces to a single PagerDuty account?

Expand

Yes, you can map multiple workspaces to a single PagerDuty account by repeating the Initial Configuration.

Can I connect a workspace to both a PagerDuty account in the US service region and a PagerDuty account in the EU service region?

Expand

Yes, you can map a single workspace to PagerDuty accounts in different regions. You'll just need to make sure to run slash commands with the appropriate prefix (/pd for US and /pdeu for EU).

How do I view on-call information in Slack?

Expand

Use the command /pd oncall to see who is on call.

What does 403_client_error mean when I run the /pd trigger command?

Expand

You are likely attempting to trigger an incident from a Slack channel that is not connected to PagerDuty. Please double check that you’ve completed all steps of the Initial Configuration.