team/docs/main/integrations-guide/incoming-webhooks.mdx

---
title: "Incoming Webhooks"
---
<PlanAvailability slug="all-commercial" />

**Technical complexity:** [No-code](./faq#no-code)

Send or receive real-time data from external tools. Webhooks require minimal coding and are easy to set up with virtually any tool or platform because they use lightweight HTTP POST requests with JSON payloads.

Using incoming webhooks in Mattermost requires only basic setup. You generate a webhook URL using the Mattermost interface, then point another service to send data to that address. No coding is required if your external service triggering the events is able to send data via webhooks or HTTP POST requests, which most modern applications and platforms support. Setting this up usually involves pasting the Mattermost webhook URL into the service’s settings and selecting what type of events you want it to send.

## Example Use Cases

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

**Monitoring alerts**

Send real-time alerts from monitoring systems (such as Prometheus or Datadog) into a dedicated Mattermost channel so your team is immediately notified about system issues or downtime.

**Build and deployment notifications**

Post automated updates from CI/CD pipelines (such as Jenkins or GitLab CI) to a channel, keeping developers informed of build status, test results, and deployment progress.

**Customer support updates**

Forward new support ticket notifications from systems like Zendesk or ServiceNow into a support channel, ensuring the team can respond quickly to incoming requests.

## Create

1.  In Mattermost, go to **Product Menu \> Integrations**. If you don't have the **Integrations** option, incoming 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 **Incoming Webhooks**.

> ![Dialog box showing the option to add an incoming webhook.](/images/manage-webhooks.png)

3.  Select **Add Incoming Webhook**.

> ![Dialog box showing the option to add an incoming webhook.](/images/select-add-incoming-webhook.png)

4.  Enter a name and description for the webhook, and then select the channel. You can optionally limit bot posts to a specific channel by selecting **Lock to this channel**, or you can allow the webhook to post to any public channel or private channel the incoming webhook creator is a member of. Note that administrators can enforce channel locking for all incoming webhooks through **System Console \> Integrations \> Integration Management**. Select **Save**.

> ![Dialog box showing the incoming webhook details.](/images/create-incoming-webhook-details.png)

5\. Select **Done** to confirm. Mattermost generates a unique webhook URL, which will look something like this: `https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx`. Treat this URL as a secret. Anyone who has it will be able to post messages to your Mattermost instance.

> ![Dialog box showing the incoming webhook URL.](/images/incoming-webhook-created.png)

## Use

To post a message, your application needs to send an HTTP POST request to the webhook URL with a JSON payload in the request body.

``` bash
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, this is some text\nThis is more text. :tada:"}' https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx
```

A successful request will receive an HTTP 200 response with <code>ok</code> in the response body.

For compatibility with Slack incoming webhooks, if no `Content-Type` header is set, the request body must be prefixed with `payload=`.

### Post Examples

Here are some examples of simple messages posted using incoming webhooks:

<img src="../images/github-incoming-webhook.png" width="400" alt="Example of a GitHub notification posted to Mattermost using an incoming webhook." />

<img src="../images/jira-incoming-webhook.png" width="400" alt="Example of a Jira notification posted to Mattermost using an incoming webhook." />

<img src="../images/mattermost-incoming-webhook.png" width="400" alt="Example of a Mattermost notification posted to Mattermost using an incoming webhook." />

<img src="../images/fastlane-incoming-webhook.png" width="400" alt="Example of a Fastlane notification posted to Mattermost using an incoming webhook." />

<img src="../images/weblate-incoming-webhook.png" width="400" alt="Example of a Weblate notification posted to Mattermost using an incoming webhook." />

## Parameters

The JSON payload can contain the following parameters:

<table>
<colgroup>
<col style={{width: '20%'}} />
<col style={{width: '15%'}} />
<col style={{width: '65%'}} />
</colgroup>
<thead>
<tr>
<th>Parameter</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>text</code></td>
<td>Yes (if <code>attachments</code> is not set)</td>
<td><a href="mm-doc:%2Fend-user-guide%2Fcollaborate%2Fformat-messages">Markdown-formatted</a> message. Use <code>@&lt;username&gt;</code>, <code>@channel</code>, and <code>@here</code> for notifications.</td>
</tr>
<tr>
<td><code>channel</code></td>
<td>No</td>
<td>Overrides the default channel. Use the channel's name (e.g., <code>town-square</code>), not the display name. Use <code>@&lt;username&gt;</code> to send a Direct Message. The webhook can post to any public channel, and any private channel the creator is a member of.</td>
</tr>
<tr>
<td><code>username</code></td>
<td>No</td>
<td>Overrides the default username. The <a href="mm-ref:administration-guide%2Fconfigure%2Fintegrations-configuration-settings%3Aenable%20integrations%20to%20override%20usernames">Enable integrations to override usernames</a> setting must be enabled.</td>
</tr>
<tr>
<td><code>icon_url</code></td>
<td>No</td>
<td>Overrides the default profile picture URL. The <a href="mm-ref:administration-guide%2Fconfigure%2Fintegrations-configuration-settings%3Aenable%20integrations%20to%20override%20profile%20picture%20icons">Enable integrations to override profile picture icons</a> setting must be enabled.</td>
</tr>
<tr>
<td><code>icon_emoji</code></td>
<td>No</td>
<td>Overrides the <code>icon_url</code> with an emoji. Use the emoji name (e.g., <code>:tada:</code>). The <a href="mm-ref:administration-guide%2Fconfigure%2Fintegrations-configuration-settings%3Aenable%20integrations%20to%20override%20profile%20picture%20icons">Enable integrations to override profile picture icons</a> setting must be enabled.</td>
</tr>
<tr>
<td><code>attachments</code></td>
<td>Yes (if <code>text</code> is not set)</td>
<td>An array of <a href="https://developers.mattermost.com/integrate/reference/message-attachments/">message attachment</a> objects for richer formatting.</td>
</tr>
<tr>
<td><code>type</code></td>
<td>No</td>
<td>Sets the post type, mainly for use by plugins. If set, must begin with <code>custom_</code>.</td>
</tr>
<tr>
<td><code>props</code></td>
<td>No</td>
<td>A JSON object for storing metadata. The <code>card</code> property can be used to display extra Markdown-formatted text in the post's info panel (RHS). This is available in Mattermost v5.14 and later, and is not yet supported on mobile.</td>
</tr>
<tr>
<td><code>priority</code></td>
<td>No</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
{
  "channel": "town-square",
  "username": "test-automation",
  "icon_url": "https://mattermost.com/wp-content/uploads/2022/02/icon.png",
  "text": "#### Test results for July 27th, 2017\n@channel please review failed tests.\n\n| Component  | Tests Run   | Tests Failed                                   |\n|:-----------|:-----------:|:-----------------------------------------------|\n| Server     | 948         | :white_check_mark: 0                           |\n| Web Client | 123         | :warning: 2 [(see details)](https://linktologs) |\n| iOS Client | 78          | :warning: 3 [(see details)](https://linktologs) |"
}
```

This renders as:

<img src="../images/incoming_webhooks_full_example.png" width="400" alt="Example of a webhook post with a custom username, icon, and formatted text." />

### Example with Card Prop

Using the `card` property inside `props` will display an info icon on the post. Clicking the icon opens the right-hand sidebar to display the content.

``` json
{
  "channel": "town-square",
  "username": "Winning-bot",
  "text": "#### We won a new deal!",
  "props": {
    "card": "Salesforce Opportunity Information:\n\n [Opportunity Name](https://salesforce.com/OPPORTUNITY_ID)\n\n-Salesperson: **Bob McKnight** \n\n Amount: **$300,020.00**"
  }
}
```

![Example of a post with a card property displaying more information in the sidebar.](/images/card-prop-example.png)

## Slack Compatibility

Mattermost provides compatibility with Slack's webhook format to make migration easier.

### Translating Slack's Data Format

Mattermost automatically translates JSON payloads from Slack format:

- `[https://mattermost.com/](https://mattermost.com/)` is rendered as a link.
- `<https://mattermost.com/|Click here>` is rendered as linked text.
- `&lt;userid&gt;` triggers a user mention.
- `<!channel>`, `<!here>`, or `<!all>` trigger channel-wide mentions.

You can also send a direct message by overriding the channel name with `@username`, e.g., `"channel": "@jim"`.

### Using Mattermost Webhooks in GitLab

You can use GitLab's built-in Slack integration to send notifications to Mattermost:

1.  In GitLab, go to **Settings \> Services** and select **Slack**.
2.  Paste the Mattermost incoming webhook URL.
3.  Optionally, set a **Username**. Leave the **Channel** field blank.
4.  Select **Save** and test the integration.

### Known Slack Compatibility Issues

- Referencing channels using `<#CHANNEL_ID>` is not supported.
- `<!everyone>` and `<!group>` are not supported.
- `*bold*` formatting is not supported; use `**bold**` instead.
- Webhooks cannot send a direct message to the user who created the webhook.

## Troubleshooting

To debug incoming webhooks, a System Admin can enable **Webhook Debugging** and set the **Console Log Level** to **DEBUG** in **System Console \> Logging**.

Common error messages include:

- **Couldn't find the channel**: The channel specified in the `channel` parameter does not exist.
- **Couldn't find the user**: The user specified does not exist.
- **Unable to parse incoming data**: The JSON payload is malformed.

If your integration posts the JSON payload as plain text instead of a rendered message, ensure the request includes the `Content-Type: application/json` header.

## Do More with Incoming Webhooks

Transform basic message posts into rich, interactive notifications by including buttons, menus, and other interactive elements in your webhook messages, making them more engaging and useful for your team.

- [Message Attachments](https://developers.mattermost.com/integrate/reference/message-attachments/): Present rich, structured summaries such as status, priority, fields, links, or images for faster triage and comprehension. (Slack‑compatible schema.)
- [Interactive Messages](https://developers.mattermost.com/integrate/plugins/interactive-messages): Make notifications actionable with buttons or menus such as Acknowledge, Assign, or Escalate that enable an immediate user response without switching tools or context.
- [Interactive Dialogs](https://developers.mattermost.com/integrate/plugins/interactive-dialogs/): Guide users to successful outcomes when interactions need structured input or confirmation (for example, “Acknowledge with note” or “Assign to user”). Improve data quality with required fields, minimum/maximum input lengths, server‑driven user/channel pickers, validated defaults, inline field errors, placeholders, and help text that help users enter the right data the first time.
- [Message Priority](https://developers.mattermost.com/integrate/reference/message-priority/): Set `priority` to elevate critical posts and optionally request acknowledgements or persistent notifications.

<Tip>

- 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 system later needs to call Mattermost APIs (e.g., post follow-ups, open dialogs), 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.

</Tip>