Outgoing Webhooks

Outgoing webhooks let Mattermost send data out when users post messages that match certain triggers. You can configure a trigger word or phrase in a specific channel, along with a destination URL. When someone posts a matching message, Mattermost sends the post content to the external URL via HTTP POST. The receiving system can then process the data and optionally respond with a message back to Mattermost. Response posts are created under the outgoing webhook’s creator. Username/icon can be overridden in the response.

For example, a user types /weather Boston as a message, and your webhook calls a weather API, which sends the current forecast back into the channel. When a message in a specified channel matches one of the trigger words, an HTTP POST request is sent to the designated URL, allowing the external application to respond.

Create

1. In Mattermost, go to Product Menu > Integrations. If you don’t have the Integrations option, outgoing webhooks may not be enabled on your Mattermost server or may be disabled for non-admins. A System Admin can enable them from System Console > Integrations > Integration Management.

2. From the Integrations page, select Outgoing Webhooks.

3. Select Add Outgoing Webhook.

4. Enter a name and description for the webhook.

5. Specify the Content Type for the request.

• application/json will send a JSON object.

• application/x-www-form-urlencoded will encode the parameters in the URL.

6. Specify a Channel and/or one or more Trigger Words.

• If you specify a channel, the webhook will only fire for messages in that channel.

• If you specify trigger words, the webhook will only fire when a message starts with one of those words.

• If both are specified, the message must match both conditions.

• If you leave the channel blank, the webhook will listen to all public channels in your team.

• If you leave the trigger words blank, the webhook will respond to all messages in the selected channel.

7. Set one or more Callback URLs that the HTTP POST requests will be sent to. Select Save.

8. Copy the Token value. This token is used to verify that the requests are coming from Mattermost.

Use

When a message triggers the webhook, Mattermost will send an HTTP POST request to the callback URL(s) you specified.

Request Payload

The request body will contain the following data (either as JSON or URL-encoded, depending on the content type you selected):

Parameter	Description
token	The token generated when you created the webhook.
team_id	The ID of the team the message was posted in.
team_domain	The domain of the team.
channel_id	The ID of the channel the message was posted in.
channel_name	The name of the channel.
timestamp	The time the message was posted.
user_id	The ID of the user who posted the message.
user_name	The username of the user who posted the message.
post_id	The ID of the post.
text	The full text of the message.
trigger_word	The trigger word that was matched.

Your application should validate the token to ensure the request is from Mattermost.

Response Payload

Your application can respond to the POST request with a JSON object to post a message back to Mattermost.

{
  "text": "| Component  | Tests Run | Tests Failed |\n|:-----------|:----------|:-------------|\n| Server     | 948       | :white_check_mark: 0 |"
}

This would render in Mattermost as:

Response Parameters

The JSON response can contain the following parameters:

Parameter	Description
text	(Required if attachments is not set) Markdown-formatted message.
response_type	Set to comment to reply to the message that triggered the webhook. Defaults to post, which creates a new message.
username	Overrides the default username. Requires Enable integrations to override usernames to be enabled.
icon_url	Overrides the default profile picture. Requires Enable integrations to override profile picture icons to be enabled.
attachments	(Required if text is not set) An array of message attachment objects.
type	Sets the post type, mainly for plugins. If set, must begin with custom_.
props	A JSON object for storing metadata.
priority	Sets the priority of the message. See message priorities.

Example with Parameters

{
  "response_type": "comment",
  "username": "test-automation",
  "icon_url": "https://mattermost.com/wp-content/uploads/2022/02/icon.png",
  "text": "#### Test results for July 27th, 2017\n@channel here are the requested test results.",
  "props": {
    "test_data": {
      "server": 948,
      "web": 123,
      "ios": 78
    }
  }
}

This response would produce a threaded reply to the original message that triggered the webhook.

You can also include message attachments and interactive messages in your response to create more advanced workflows.

Do More with Outgoing Webhooks

Turn keyword-triggered callbacks into guided, in-channel workflows by returning buttons, menus, and other interactive elements in your webhook responses so users can act immediately.

• Message Attachments: Return rich, structured results (IDs, statuses, fields, links, images) for quick confirmation and follow-up.

• Interactive Messages: Present next-step actions (Acknowledge, Assign, Escalate) as buttons/menus directly in your response—no context switching.

• Interactive Dialogs: When a button/menu click requires more info (e.g., “Acknowledge with note”, “Assign to user”), open a dialog to collect structured inputs with required fields, min/max lengths, server-driven user/channel pickers, validated defaults, inline field errors, placeholders, and help text.

• Message Priority: Include priority in your response to mark critical updates and optionally request acknowledgements or persistent notifications.

Note

• Outgoing webhook responses support attachments and interactive actions. When a user clicks an action, your integration receives a signed trigger ID and can open an interactive dialog via the dialog API. You can also control visibility with the response type (in-channel vs ephemeral).

• Need a dedicated identity, permissions scoping, or need to post outside of webhook/command flows? Use a bot account if you need a more permanent solution than using overrides for simple branding.

• If your command backend needs to call Mattermost APIs (e.g., posting messages, ephemeral posts, opening interactive dialogs, etc.), authenticate with a bot user personal access token. We recommend avoiding human/System Admin personal access tokens for automations and rotating and storing tokens securely.

• Looking to support private channels, direct messages, and autocomplete? Use a built-in slash command, or create a custom slash command. You can additionally tegrate Mattermost with custom integrations hosted within your internal OAuth infrastructure using the Client Credentials OAuth 2.0 grant type. Mattermost also makes it easy to migrate integrations written for Slack to Mattermost.