Slack Integration Guide | PagerDuty

Slack + PagerDuty Integration Benefits

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 or V1 to Slack V2 Next Generation.
  • Slack V1 will be deprecated on November 1, 2021 and accounts using this version must migrate to Slack V2 Next Generation (Recommended) or Slack V2 before that date. Please note that while V1 webhooks are deprecating on November 13, 2021, the Slack V1 integration will be deprecated earlier on November 1 and will cease working after that date.

📘

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.

📘

Looking for Another Version?

The following versions are also available:

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.

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. I.e., 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.

Integration Walkthrough

Initial Configuration

  1. First you will need to map your PagerDuty account to your Slack Workspace.
  2. Navigate to Integrations Extensions. Select the top Slack tile.
  3. On the Slack Workspace Mapping screen, click the Install App into Workspace button 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.
  4. On the next screen, you will be asked to authorize the PagerDuty for Slack integration to perform the following actions:
  • 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. 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

  1. 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:

Field

Value

PagerDuty Source

Select your preferred service or team.

Slack channel

Select your preferred channel.

Notification type

Select the radio button for Responder or Stakeholder notifications.

Notify the channel of these updates:

You may check or uncheck the following update types:

  • Acknowledged
  • Unacknowledged
  • Escalated
  • Resolved
  • Reassigned
  • Note added
  • Delegated
  • Priority changed
  • Reopened
  • Responder requested
  • Responder joined / declined
  • Status update added

When the incident matches these criteria:

  • Urgency: Select your preferred urgency.
  • Priority: Select your preferred priority.

Click Add Connection to connect your PagerDuty source to your Slack channel. To add multiple channel connections, repeat step 5 as many times as needed.

  1. The Slack integration is now complete. You should see a message in your designated Slack channel that the PagerDuty integration has been added. If you set up the integration on a private channel, add @pagerduty to your channel.
  2. When an incident is triggered, the incident notification message in Slack will show Acknowledge and Resolve buttons, and under the More actions… menu, you will see the options View Details, Add a Note, Escalate, Run a Play, View | Create Channel, New Status Update.

Available Slash Commands

Once the updated integration has been installed, new slash commands will be available. These slash commands can be run from Slack channels that are configured with PagerDuty:

  • /pd help: Displays a help message with a list of these 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.

🚧

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.

Creating On-Demand Slack Channels

With the updated Slack integration, PagerDuty users can create on-demand Slack channels from PagerDuty incidents, and from Slack incident notifications.

🚧

User Permission Notes

  • When you click Set Channel you may be prompted to authorize the connection between your PagerDuty and Slack accounts again, as PagerDuty will now be creating a channel behalf of your individual Slack user account.
  • You will only be able to view channels that you have permission in Slack to access.
  • If you do not have permission in Slack to create channels, you will not be able to create them from the Set Channel link in a PagerDuty incident.
  • If your PagerDuty account has multiple Slack workspaces connected, you will have the option to pick 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. You will have the ability to create new public or private channels or associate an existing channel with an incident.

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. A Slack channel for this incident will automatically be created.

Create an Incident Trigger Slack Workflow

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

  1. In your Slack desktop, 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, to create a form for users to enter incident Titles and Descriptions, click Add Step and then click Add next to Create a form. Enter a Title for the form, such as Trigger PD incident, enter Title under Add a question, select Short answer and ensure Make this required is checked. Next, click Add Question and enter Description under Add a question, select Short answer, ensure Make this required is checked and click Done. Uncheck Send submitted responses to a channel or to someone in a DM and then click Save to save both forms.
  4. Next, click Add Step, select the Steps from Apps tab, search and then select Trigger Incident. You will be prompted to sign into your PagerDuty account, click Sign in. Once signed in, the Trigger Incident Step will be added to your Slack workflow. Select your preferred Impacted service, optionally select the Assign to user and optionally select your preferred Priority. Next, under Title click Insert a variable and select Response to: “Title” to add the Title form. Similarly, under Description, click Insert a variable and select Response to: “Description” and then click Save. If you would like to add an optional message to be sent with this workflow, continue to step 5. If you do not want to add a message, skip to step 6.
  5. 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.
  6. Finally, click Publish in the upper right to publish your workflow.

Use an Incident Trigger Slack Workflow

  1. In your Slack desktop, enter a channel with an Incident Trigger Slack Workflow configured and click the Shortcuts at the bottom left of your text field and select the Trigger PD incident workflow.
  2. Enter the Title and Description of the incident and click Submit.
  3. The incident will be created in PagerDuty and you will be able to see the incident details in your Slack channel.

Granular Bot Permissions

Slack now 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 could 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 Slack admin to approve connection. If a Slack Admin does not approve the new changes, users will not be able to create new Slack channel and PagerDuty service connections. If your Slack account has not restricted these settings, no action is necessary.

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

OAuth Scope

Slack Description

PagerDuty Request Reason

app_mentions:read

View messages that directly mention @pagerduty in conversations that the app is in.

Used for interactions with PagerDuty bot and responding to commands.

channels:join

Join public channels in a workspace.

After a public channel has been created, we will use this scope to join the channel.

channels:manage

Manage public channels that PagerDuty has been added to and create new ones.

This will allow us to create public channels.

channels:read

View basic information about public channels in a workspace.

Getting user IDs from a channel in order to prompt those users about associating their PagerDuty user to their Slack username.

chat:write

Send messages as @pagerduty.

Used to post incident notifications to channels in Slack.

chat:write.public

Send messages to channels @pagerduty isn't a member of.

Used to post incident notifications to channels in Slack.

commands

Add shortcuts and/or slash commands that people can use.

Used for interactions with the PagerDuty bot and responding to commands.

groups:read

View basic information about private channels that PagerDuty has been added to.

Access information about a user’s private channels: Getting user IDs from a private channel in order to prompt those users about associating their PagerDuty user to their slack username.

groups:write

Manage private channels that PagerDuty has been added to and create new ones

This will allow us to create a private channel for PagerDuty incident.

im:read

View basic information about direct messages that PagerDuty has been added to.

Getting user IDs from a multi-party direct message (private messages to a specific group users) in order to prompt those users about associating their PagerDuty user to their Slack username.

im:write

Start direct messages with people.

Replying to a multi-party direct message about associating their PagerDuty user to their Slack username.

incoming-webhook

Post messages to specific channels in Slack.

PagerDuty communicates with Slack via webhooks to notify users of a new incident in PagerDuty. Used to post to channels in slack.

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, admins should visit Integrations Extensions Slack Integration. If reauthorization is required, you will see a Reauthorize button 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.

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.

Complete Slack Webhook Migration

Our Migration Tool makes migrating to Slack V2 Next Generation easy. 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.
  • Once you have migrated, the ability to create Slack V1 and Slack V2 connections (via V2 webhook extensions) will be disabled. This means Terraform and old extension APIs will stop working and only Slack V2 Next Generation connections (via V3 webhook subscriptions) will be able to be created.
  • After migration, you will only be able to manage Slack channel connections via the new Slack Connection Management page. You will no longer be able to manage them at the service level.

🚧

Requirements

  • In order to configure the Slack V2 Next Generation update, you must complete the Slack webhook migration first.
  • 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.
  • 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. Navigate to Integrations Extensions and click the Slack Integration tile at the top of the page.
  2. Next, in the first yellow banner at the top of the page, click Migration Overview.
  1. Follow the Migration widget 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 user with PagerDuty Admin or higher and Slack Workspace Admin or higher can perform these actions.

🚧

Webhooks V3 Update

  • Once the migration has started, it cannot be cancelled. Migration will only need to be completed once.
  • After migration, the ability to create Slack V1 and Slack V2 connections (via V2 webhook extensions) will be disabled. This means Terraform and old extension APIs will stop working and only Slack V2 Next Generation connections (via V3 webhook subscriptions) will be able to be created.
  • During migration, incident notifications, updates, and actions will continue to occur in Slack. You may receive duplicate incident notifications during migration.

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

With the latest Slack V2 Next Generation update, 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, Managers, Admins and Account Owners can now manage connections on the Slack Connection Management page. They will no longer be able to use the service page for this purpose.

🚧

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

  1. Navigate to Integrations Extensions and click the Slack Integration tile at the top of the page. Click View to the right of your desired workspace and then click Add Connection.
  2. Make selections in the following fields based on your preference:

Field

Value

PagerDuty Source

Select your preferred service or team.

Slack channel

Select your preferred channel.

Notification type

Select the radio button for Responder or Stakeholder notifications.

Notify the channel of these updates:

You may check or uncheck the following update types:

  • Acknowledged
  • Unacknowledged
  • Escalated
  • Resolved
  • Reassigned
  • Note added
  • Delegated
  • Priority changed
  • Reopened
  • Responder requested
  • Responder joined / declined
  • Status update added

When the incident matches these criteria:

  • Urgency: Select your preferred urgency.
  • Priority: Select your preferred priority.

Click Add Connection to connect your PagerDuty Source to your Slack channel.

Edit or Remove a Slack Channel Connection

  1. Navigate to Integrations Extensions and click the Slack Integration tile at the top of the page. 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.

Revoke Workspace Connection

  1. Navigate to Integrations Extensions and click the Slack Integration tile at the top of the page. Click View to the right of your desired workspace.
  2. Under Authorized Workspace, click Revoke to the right. Enter disconnect in the modal field and click Remove Connection.

PagerDuty Slack Integration API

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

FAQ

If I already have the Slack V1 or V2 extension installed, can I update to Slack V2 Next Generation?

Yes, please follow instructions here to use our migration tool.

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

No. Incident notifications, updates, and actions will continue to occur 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?

No, this is not required.

Why is workspace mapping required for Slack V2 Next Generation?

Workspace mapping is connecting a Pagerduty account to a Slack workspace. This provides access/authorization to all channels in a workspace. This removes the need for per-channel connection authorization

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

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?

With Next Gen Slack V2, Customers can trigger an incident without a PagerDuty license by using the Slack WorkFlow Step: Trigger an Incident in PagerDuty

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

Yes. Once you have migrated to Slack V2 Next Generation, the expectation is that the old (webhook V2 and V1) Slack connections can no longer be created. This means connections can only be created via the Connection Management page.

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

You'll need to invite the PagerDuty bot into your Slack channel after you set it to private.

Do I need to install anything separate to use the slash command?

No. In the Slack V2 Next Generation integration, this is no longer a separate app. You do need to ensure that you map the Slack extension and your Slack workspace to PagerDuty (step 4 of the Integration Walkthrough), and then the /pd trigger command will function. Note: At the moment, only PagerDuty users can use /pd trigger.

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

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

How do I view on-call information in Slack?

You can do this by running the /pd oncall command.

What do I do if I’m seeing a 403_client_error when running the /pd trigger command?

You are likely attempting to trigger an incident from a Slack channel that is not connected to PagerDuty. Ensure that you have connected Slack to PagerDuty as shown in step 3 above.

How do I provide feedback, suggestions and/or bugs?

Please contact our Support team.

Updated 2 days ago


Learn more

Please visit our Slack V1 FAQ for more information.

Slack V1 Integration Guide

Slack Integration Guide | PagerDuty


Suggested Edits are limited on API Reference Pages

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