Outgoing Webhooks

Available on Entry, Professional, Enterprise, and Enterprise Advanced plans

Technical complexity: Low-code

Outgoing webhooks can be used to create rich, interactive experiences in Mattermost by letting external services respond with Mattermost Blocks—structured content with buttons, menus, and other interactive elements. Additionally, these responses can trigger interactive dialog forms where users provide additional input directly in Mattermost. Together, these capabilities turn simple keyword triggers into powerful in-product workflows that streamline how teams interact with external systems, all with minimal coding required.

Outgoing webhooks require no coding to configure on in Mattermost, however the external service that receives the HTTP POST request needs to process the data, and then format and send a respond with a message back to Mattermost. This usually requires light coding to parse the request and format a JSON response payload, though many automation platforms handle this without writing custom code.

Learn more about outgoing webhooks.

Example Use Cases

Here are some example use cases for outgoing webhooks in Mattermost:

Issue tracking integration

When a user types bug in a channel, an outgoing webhook sends the message to an external service that parses the details and responds with an interactive dialog in Mattermost. The user can enter fields like priority, description, and assignee, and submitting the dialog automatically creates a ticket in your ticketing software.

Knowledge base lookup

A keyword like docs triggers an outgoing webhook that queries a documentation service and returns a response with Mattermost Blocks listing suggested articles, each with clickable buttons or menus. Users can refine their search or open links without leaving Mattermost.

Security incident enrichment

Typing a keyword like ioc (indicator of compromise) in a security channel can trigger an outgoing webhook that queries a threat intelligence platform. The response can return Mattermost Blocks with reputation scores, related incidents, and quick-action buttons for escalating, investigating, or dismissing the alert.

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 unless attachments or props.mm_blocks is 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	Legacy array of message attachment objects. Use Mattermost Blocks for new integrations.
type	Sets the post type, mainly for plugins. If set, must begin with custom_.
props	A JSON object for storing metadata. Use Mattermost Blocks for rich, interactive content.
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 Mattermost Blocks 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.

• Mattermost Blocks: Return structured, interactive content with text, buttons, and menus.
• 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.

iNote

• Outgoing webhook responses support Mattermost Blocks and interactive actions. The outgoing webhook response_type accepts post or comment. When a user clicks an action, the callback payload includes a trigger_id field that can be used to open an interactive dialog; the trigger ID isn't a request signature. Return ephemeral_text in the action response when feedback should be visible only to the user who clicked the action.
• 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 integrate 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.