snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/main/integrations-guide/outgoing-webhooks.mdx

@@ -0,0 +1,243 @@
+---
+title: "Outgoing Webhooks"
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+<PlanAvailability slug="all-commercial" />
+
+**Technical complexity:** [Low-code](./faq#low-code)
+
+Outgoing webhooks can be used to create rich, interactive experiences in Mattermost by letting external services respond with [Mattermost Blocks](https://developers.mattermost.com/integrate/reference/mm-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](/integrations-guide/integrations-guide-index#build-and-automate-workflows) handle this without writing custom code.
+
+Learn more about [outgoing webhooks](/integrations-guide/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](https://developers.mattermost.com/integrate/reference/mm-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](https://developers.mattermost.com/integrate/reference/mm-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**.
+
+> ![Mattermost menu options showing the ability to work with integrations.](/images/product-menu-integrations.png)
+
+2.  From the Integrations page, select **Outgoing Webhooks**.
+
+> ![Dialog box showing the option to add an outgoing webhook.](/images/manage-webhooks.png)
+
+3.  Select **Add Outgoing Webhook**.
+
+> ![Dialog box showing the option to add an outgoing webhook.](/images/select-add-outgoing-webhook.png)
+
+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.
+>
+> ![Dialog box showing the outgoing webhook details.](/images/create-outgoing-webhook-details.png)
+
+7.  Set one or more **Callback URLs** that the HTTP POST requests will be sent to. Select **Save**.
+
+> ![Dialog box showing the outgoing webhook callback URLs.](/images/create-outgoing-webhook-details-more.png)
+
+8.  Copy the **Token** value. This token is used to verify that the requests are coming from Mattermost.
+
+![Dialog box showing the outgoing webhook token.](/images/outgoing-webhook-created.png)
+
+## 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):
+
+<table>
+<colgroup>
+<col style={{width: '25%'}} />
+<col style={{width: '75%'}} />
+</colgroup>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>token</code></td>
+<td>The token generated when you created the webhook.</td>
+</tr>
+<tr>
+<td><code>team_id</code></td>
+<td>The ID of the team the message was posted in.</td>
+</tr>
+<tr>
+<td><code>team_domain</code></td>
+<td>The domain of the team.</td>
+</tr>
+<tr>
+<td><code>channel_id</code></td>
+<td>The ID of the channel the message was posted in.</td>
+</tr>
+<tr>
+<td><code>channel_name</code></td>
+<td>The name of the channel.</td>
+</tr>
+<tr>
+<td><code>timestamp</code></td>
+<td>The time the message was posted.</td>
+</tr>
+<tr>
+<td><code>user_id</code></td>
+<td>The ID of the user who posted the message.</td>
+</tr>
+<tr>
+<td><code>user_name</code></td>
+<td>The username of the user who posted the message.</td>
+</tr>
+<tr>
+<td><code>post_id</code></td>
+<td>The ID of the post.</td>
+</tr>
+<tr>
+<td><code>text</code></td>
+<td>The full text of the message.</td>
+</tr>
+<tr>
+<td><code>trigger_word</code></td>
+<td>The trigger word that was matched.</td>
+</tr>
+</tbody>
+</table>
+
+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.
+
+``` json
+{
+  "text": "| Component  | Tests Run | Tests Failed |\n|:-----------|:----------|:-------------|\n| Server     | 948       | :white_check_mark: 0 |"
+}
+```
+
+This would render in Mattermost as:
+
+![Example of a formatted table response from an outgoing webhook.](/images/webhooksTable.png)
+
+## Response Parameters
+
+The JSON response can contain the following parameters:
+
+<table>
+<colgroup>
+<col style={{width: '20%'}} />
+<col style={{width: '80%'}} />
+</colgroup>
+<thead>
+<tr>
+<th>Parameter</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>text</code></td>
+<td>(Required unless <code>attachments</code> or <code>props.mm_blocks</code> is set) <a href="/end-user-guide/collaborate/format-messages">Markdown-formatted</a> message.</td>
+</tr>
+<tr>
+<td><code>response_type</code></td>
+<td>Set to <code>comment</code> to reply to the message that triggered the webhook. Defaults to <code>post</code>, which creates a new message.</td>
+</tr>
+<tr>
+<td><code>username</code></td>
+<td>Overrides the default username. Requires <a href="/administration-guide/configure/integrations-configuration-settings#enable-integrations-to-override-usernames">Enable integrations to override usernames</a> to be enabled.</td>
+</tr>
+<tr>
+<td><code>icon_url</code></td>
+<td>Overrides the default profile picture. Requires <a href="/administration-guide/configure/integrations-configuration-settings#enable-integrations-to-override-profile-picture-icons">Enable integrations to override profile picture icons</a> to be enabled.</td>
+</tr>
+<tr>
+<td><code>attachments</code></td>
+<td>Legacy array of <a href="https://developers.mattermost.com/integrate/reference/message-attachments/">message attachment</a> objects. Use Mattermost Blocks for new integrations.</td>
+</tr>
+<tr>
+<td><code>type</code></td>
+<td>Sets the post type, mainly for plugins. If set, must begin with <code>custom_</code>.</td>
+</tr>
+<tr>
+<td><code>props</code></td>
+<td>A JSON object for storing metadata. Use <a href="https://developers.mattermost.com/integrate/reference/mm-blocks/">Mattermost Blocks</a> for rich, interactive content.</td>
+</tr>
+<tr>
+<td><code>priority</code></td>
+<td>Sets the priority of the message. See <a href="https://developers.mattermost.com/integrate/reference/message-priority/">message priorities</a>.</td>
+</tr>
+</tbody>
+</table>
+
+### Example with Parameters
+
+``` json
+{
+  "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.
+
+<img src={useBaseUrl('/images/outgoing_webhooks_full_example.png')} width="400" alt="Example of a full response from an outgoing webhook." />
+
+You can also include [Mattermost Blocks](https://developers.mattermost.com/integrate/reference/mm-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](https://developers.mattermost.com/integrate/reference/mm-blocks/): Return structured, interactive content with text, buttons, and menus.
+- [Interactive Dialogs](https://developers.mattermost.com/integrate/plugins/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](https://developers.mattermost.com/integrate/reference/message-priority/): Include `priority` in your response to mark critical updates and optionally request acknowledgements or persistent notifications.
+
+<Note>
+
+- Outgoing webhook responses support Mattermost Blocks and interactive actions. The outgoing webhook <code>response_type</code> accepts <code>post</code> or <code>comment</code>. When a user clicks an action, the callback payload includes a <code>trigger_id</code> field that can be used to open an interactive dialog; the trigger ID isn't a request signature. Return <code>ephemeral_text</code> 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](https://developers.mattermost.com/integrate/reference/bot-accounts/) 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](https://developers.mattermost.com/integrate/reference/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](/integrations-guide/built-in-slash-commands), or create a [custom slash command](https://developers.mattermost.com/integrate/slash-commands/custom/). You can additionally integrate Mattermost with custom integrations hosted within your internal OAuth infrastructure [using the Client Credentials OAuth 2.0 grant type](https://developers.mattermost.com/integrate/slash-commands/outgoing-oauth-connections/). Mattermost also makes it easy to [migrate integrations written for Slack to Mattermost](https://developers.mattermost.com/integrate/slash-commands/slack/).
+
+</Note>