An example of a GitHub integration that posts updates to a Developers channel
Use curl, a simple command line tool for sending HTTP requests in the examples that follow.
To prevent malicious users from trying to perform phishing attacks, a BOT indicator appears next to posts coming from webhooks regardless of what username is specified.
Let’s learn how to create a simple incoming webhook that posts the following message to Mattermost.
curl -i -X POST -H 'Content-Type: application/json' -d '{"text": "Hello, this is some text\nThis is more text. :tada:"}' http://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
# or
curl -i -X POST --data-urlencode 'payload={"text": "Hello, this is some text\nThis is more text. :tada:"}' http://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
If you’re running cURL on Windows, ensure inner double quotes are escaped with a backslash. Here’s an example payload on Windows:
curl -i -X POST -H "Content-Type: application/json" -d "{\"text\": \"Hello, this is some text\nThis is more text. :tada:\"}" http://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
See developer documentation for details on what parameters are supported by incoming webhooks. For instance, you can override the username and profile picture the messages post as, or specify a custom post type when sending a webhook message for use by plugins. The following payload gives an example webhook that uses additional parameters and formatting options:
payload={
"channel": "town-square",
"username": "test-automation",
"icon_url": "https://mattermost.org/wp-content/uploads/2016/04/icon.png",
"text": "#### Test results for July 27th, 2017\n<!channel> please review failed tests.\n
| Component | Tests Run | Tests Failed |
|:-----------|:-----------:|:-----------------------------------------------|
| Server | 948 | :white_check_mark: 0 |
| Web Client | 123 | :warning: 2 [(see details)](http://linktologs) |
| iOS Client | 78 | :warning: 3 [(see details)](http://linktologs) |
"
}
This content will be displayed in the Town Square channel.
Messages with advanced formatting can be created by including an attachment array and interactive message buttons in the JSON payload.
Note: Enable integrations to override usernames must be set to true in config.json to override usernames. Enable them from System Console > Integrations > Integration Management, or ask your System Admin to do so. If not enabled, the username is set to webhook.
Similarly, Enable integrations to override profile picture icons must be set to true in config.json to override profile picture icons. Enable them from System Console > Integrations > Integration Management, or ask your System Admin to do so. If not enabled, the icon of the creator of the webhook URL is used to post messages.
Content-Type is specified as application/json in the header of the HTTP request, then the body can be direct JSON. For example,{"text": "Hello, this is some text."}
icon_emoji parameter, the user profile image is replaced by the emoji provided. This will also override the icon_url parameter if both are provided.If you’ve built an integration for Mattermost, please consider sharing your work in our app directory.
The app directory lists open source integrations developed by the Mattermost community and are available for download, customization and deployment to your private cloud or self-managed infrastructure.
Mattermost makes it easy to migrate integrations written for Slack to Mattermost. Using the Slack icon_emoji parameter overrides the profile icon and the icon_url parameter and is supported from version 5.14.
Mattermost automatically translates the data coming from Slack:
JSON payloads written for Slack, that contain the following, are translated to Mattermost markdown and rendered equivalently to Slack:
<> to denote a URL link, such as {"text": "<https://mattermost.com/>"}| within a <> to define linked text, such as {"text": "Click <https://mattermost.com/|here> for a link."}<userid> to trigger a mention to a user, such as {"text": "<5fb5f7iw8tfrfcwssd1xmx3j7y> this is a notification."}<!channel>, <!here>, or <!all> to trigger a mention to a channel, such as {"text": "<!channel> this is a notification."}You can override the channel name with a @username, such as payload={"text": "Hi", channel: "@jim"} to send a direct message like in Slack.
You can prepend a channel name with # and the message will still be sent to the correct channel like in Slack.
GitLab is the leading open-source alternative to GitHub and offers built-in integrations with Slack. You can use the Slack interface in GitLab to add Mattermost webhooks directly without changing code:
<#CHANNEL_ID> does not link to the channel.<!everyone> and <!group> are not supported.*bold* is not supported (must be done as **bold**).To debug incoming webhooks in System Console > Logs, set System Console > Logging > Enable Webhook Debugging to true, and set System Console > Logging > Console Log Level to DEBUG.
Some common error messages include:
Couldn't find the channel: Indicates that the channel doesn’t exist or is invalid. Please modify the channel parameter before sending another request.Couldn't find the user: Indicates that the user doesn’t exist or is invalid. Please modify the channel parameter before sending another request.Unable to parse incoming data: Indicates that the request received is malformed. Try reviewing that the JSON payload is in a correct format and doesn’t have typos such as extra ".curl: (3) [globbing] unmatched close brace/bracket in column N: Typically an error when using cURL on Windows, when:payload={"Hello" : "test"} or-d data, -d 'payload={"Hello":"test"}'If your integration prints the JSON payload data instead of rendering the generated message, make sure your integration is returning the application/json content-type.
For further assistance, review the Troubleshooting forum for previously reported errors, or join the Mattermost user community for troubleshooting help.
To send a message to a Direct Message channel, add an “@” symbol followed by the username to the channel parameter. You can add your own username to send the webhook posts to a Direct Message channel with yourself.
payload={"channel": "@username", "text": "Hello, this is some text\nThis is more text. :tada:"}
This will send a message from the account that has set up the incoming webhook to the username after the “@” symbol. For example, if you create a webhook with the user alice and send a Direct Message to bob using a webhook, it will show up as a direct message from alice to bob regardless of other settings such as username.
To send a message to a different Direct Mssage channel between two other users, you can specify the channel with the user IDs for the users separated with two underscore symbols. To find the user ID you can use the mattermost command.
payload={"channel": "6w41z1q367dujfaxr1nrykr5oc__94dzjnkd8igafdraw66syi1cde", "text": "Hello, this is some text\nThis is more text. :tada:"}