Incoming Webhooks¶

Enabling Incoming Webhooks¶

Incoming webhooks should be enabled on your Mattermost instance by default, but if they are not you’ll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following:

1. Login to your Mattermost team account that has the system administrator role.
2. Enable incoming webhooks from System Console > Integrations > Custom Integrations.
3. (Optional) Configure the Enable integrations to override usernames option to allow external applications to post messages under any name. If not enabled, the username is set to “webhook”.
4. (Optional) Configure the Enable integrations to override profile picture icons option to allow external applications to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages.

Setting Up Existing Integrations¶

If you’ve already found or built an integration and are just looking to hook it up, then you should just need to follow the specific instructions of that integration. If the integration is using Mattermost incoming webhooks, then at some point in the instructions it will ask for a webhook URL. You can get this URL by following the first step in the next section.

Creating Integrations using Incoming Webhooks¶

You can create a webhook integration to post into any Mattermost public channels and into private channels you have permission to by using these steps:

1. Create a Mattermost Incoming Webhook URL.

1. Login to your Mattermost team site and go to Main Menu > Integrations > Incoming Webhooks.
2. Click Add incoming webhook.
3. Select the channel to receive webhook payloads, then click Add to create the webhook.
4. To see your new webhook in action, try a curl command from your terminal or command-line to send a JSON string as the payload parameter in a HTTP POST request. For example:

curl -i -X POST -d 'payload={"text": "Hello, this is some text.\nThis is more text."}' http://{your-mattermost-site}/hooks/xxx-generatedkey-xxx

2. Build your integration in the programming language of your choice.

1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by GitLab outgoing webhooks and parse them into a JSON body to post into Mattermost.
2. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a payload that contains a JSON object that specifies a text parameter. For example, payload={"text": "Hello, this is some text."}` is a valid body for a request.
3. Set up your integration running on Heroku, an AWS server or a server of your own to start sending real-time updates to Mattermost channels.

Additional Notes:

1. For the HTTP request body, if Content-Type is specified as application/json in the headers of the HTTP request then the body of the request can be direct JSON. For example, {"text": "Hello, this is some text."}
2. You can override the channel specified in the webhook definition by specifying a channel parameter in your payload. For example, you might have a single webhook created for Town Square, but you can use payload={"channel": "off-topic", "text": "Hello, this is some text."} to send a message to the Off-Topic channel using the same webhook URL. If an @ symbol followed by a username is specified, then the message will be sent to that user’s direct message channel.
3. In addition, with Enable integrations to override usernames turned on, you can also override the username the message posts as by providing a username parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use payload={"username": "robot", "text": "Hello, this is some text."} to change the username of the post to “robot”. Note, to combat any malicious users from trying to use this to perform phishing attacks a BOT indicator appears next to posts coming from webhooks.
4. With Enable integrations to override profile picture icons turned on, you can similarly change the icon the message posts with by providing a link to an image in the icon_url parameter of your payload. For example, payload={"icon_url": "http://example.com/somecoolimage.jpg", "text": "Hello, this is some text."} will post using whatever image is located at http://example.com/somecoolimage.jpg as the icon for the post.
5. Also, as mentioned previously, markdown can be used to create richly formatted payloads, for example: payload={"text": "# A Header\nThe _text_ below **the** header."} creates a message with a header, a carriage return, and bold text for “the”.
6. Including @username in the JSON payload will trigger a mention notification for the person with the specified username. Channels can be mentioned by including @channel or <!channel>. For example: payload={"text": "<!channel> this is a notification""} would create a message that mentions @channel.
7. If the text is longer than 4000 characters, the message is split into multiple consecutive posts, each within the 4000 character limit.
8. Posts with advanced formatting can be created by including an attachment array in the JSON payload.

Slack Compatibility¶

Mattermost makes it easy to take integrations written for Slack’s proprietary JSON payload format and repurpose them to become Mattermost integrations. For example:

Troubleshooting¶