Mattermost Integration Guide

Mattermost provides an enterprise messaging workspace for teams to collaborate securely and effectively. Its scalable solutions offer a centralized hub for intra-company communications that increase agility, efficiency and innovation while meeting advanced security, compliance and audit requirements, which may include deployment to AWS, Azure and private clouds, or even to on-prem environments. Mattermost can be configured with PagerDuty to receive all incident updates for any PagerDuty Service in any Mattermost channel of your choice. This integration automatically provides pertinent information regarding the state of an incident to your live chat streams, improves communication during incidents, and optimizes your team's resolution time and process.

In Mattermost

1. Log in to Mattermost as an administrator.
2. Open the system menu and select Integrations.
3. On the integrations page, select Incoming Webhook.
4. On the Incoming Webhooks management page, click Add Incoming Webhook.
5. Configure a new webhook as follows:
   • Enter descriptive content for Title and Description, i.e. "PagerDuty" / "Receive updates on PagerDuty incidents"
   • In the Channel field, select a default channel that will receive messages from PagerDuty.
   • Optionally, if you want to constrain messages to the given channel, enable the Lock to this channel option.
6. Click Save.
7. On the next page, you should be presented with a webhook URL. Copy and save this URL.

In PagerDuty

1. Navigate to a service that you wish to have send updates to Mattermost.
2. Go to the Integrations tab on the service.
3. Under Extensions, click New Extension.
4. For Extension Type, select Mattermost, and set up the extension as follows:
   • Give the extension a descriptive name, i.e. that identifies the recipients of the messages.
   • In the Mattermost webhook url field, put the webhook URL created in the above steps.
   • Leave the Channel field blank.
5. Click Save to complete the integration.

At this point, you should get update messages for PagerDuty incidents on the integrated service in the specified channel. To test the integration, you could manually trigger an incident on the service through the PagerDuty web app.

Changing the Channel of Notification

If you left the Lock to this channel option disabled, you can use the same webhook on different services for submitting incident update messages to other channels. This is done by setting the optional Channel setting on the PagerDuty extension, as follows:

1. In Mattermost, via the web interface, go to the channel that you wish to use as the recipient for PagerDuty updates.
2. Copy the last part of the URL after the final forward slash. This will usually be similar to channel name, but in lower case and with dashes in place of spaces.
3. Go to the service with the Mattermost extension on it, and go to the Integrations tab.
4. Scroll down to find the Mattermost extension, and in the cog icon menu click Edit.
5. In the Channel field, put the human-readable channel ID copied in the previous steps.

Frequently Asked Questions

What kinds of updates will show up in Mattermost?

In Mattermost, all of the following types of events will show up as incident update messages:

• Triggering, i.e. when an incident is initially created
• Reassignment (assigning to another user directly) and delegation (assigning to another escalation policy)
• Auto-escalation (due to escalation policy level timeout)
• Acknowledgement
• Resolution