In Mattermost, incoming webhooks receive data from external applications and make a post in a specified channel. They’re great for setting up notifications when something happens in an external application.

Outgoing webhooks take data from Mattermost, and send it to an external application. Then the outgoing webhook can post a response back in Mattermost. They’re great for listening in on channels, and then notifying external applications when a trigger word is said.

A slash command is similar to an outgoing webhook, but instead of listening to a channel it is used as a command tool. This means if you type in a slash command it will not be posted to a channel, whereas an outgoing webhook is only triggered by posted messages.

If you have an integration that outputs a payload in a different format you need to write an intermediate application to act as a translation layer to change it to the format Mattermost uses. Since there’s currently no general standard for webhook formatting, this is unavoidable and just a part of how webhooks work.

When “attachments” are mentioned in the integrations documentation, it refers to Slack’s Message Attachments. These “attachments” can be optionally added as an array in the data sent by an integration, and are used to customize the formatting of the message.

We currently don’t support the ability to attach files to a post made by an integration.

Visit our app directory for dozens of open source integrations to common tools like Jira, Jenkins, GitLab, Trac, Redmine, and Bitbucket, along with interactive bot applications (Hubot, mattermost-bot), and other communication tools (Email, IRC, XMPP, Threema) that are freely available for use and customization.

For self-hosted deployments in small setups you might host integrations on the same server on which Mattermost is installed. For larger deployments you can setup a separate server for integrations, or add them to the server on which the external application is hosted–for example, if you’re self-hosting a Jira server you could deploy a Jira integration on the Jira server itself.

When self-hosting restrictions are less strict, AWS, Heroku and other public cloud options could also be used.

The steps also outline how to give the account permissions to post to any channel in your Mattermost server, including direct messages, or to any public channel.

Include the personal access token from step 2 as part of the Authorization header on API requests from your integration.

To confirm the token works, you can have your bot make a simple GET request to /api/v4/users/me with the Authorization:bearer<yourtokenhere> in the header. If it returns a 200 with the bot’s user object in the response, the API request was made successfully.

The bot should retrieve the session token from the Token header and store it in memory for use with future requests.

Note: Each session token has an expiry time, set depending on the server’s configuration. If the session token your bot is using expires, it will receive a 401 Unauthorized response from requests using that token. When your bot receives this response, it should re-apply the login logic (using the above steps) to get another session token. Then re-send the request that received the 401 status code.

Include the Token as part of the Authorization header on API requests from your integration.

To confirm the token works, you can have your bot make a simple GET request to /api/v4/users/me with the Authorization:bearer<yourtokenhere> in the header. If it returns a 200 with the bot’s user object in the response, the API request was made successfully.

Note: The Mattermost development team is also working on an API developer token, which allows you to authenticate the bot account via the API token rather than retrieving a session token from a user account.

How should I automate the install and upgrade of Mattermost when included in another application?¶

Review Configuration Settings in config.json and set your automation to customize your Mattermost deployment based on your requirements.

For directory locations defined in config.json, such as the location of the local file storage directory (./data/) or logs directory (./logs), you can redefine those locations in your config.json settings and move the directories.

All other directories should remain as they are in /mattermost

Test that your Mattermost server is running with your new configuration.

Also, from the commandline run ./bin/mattermost-version to test that the commandline interface is functioning properly.