A webhook is a way for one app to send real-time data to another app.
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 used.
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.
Slack compatible means that Mattermost accepts integrations that have a payload in the same format as Slack.
If you have a Slack integration, you should be able to set it up in Mattermost without changing the format.
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.
If there’s no translation layer, Mattermost won’t understand the data you’re sending.
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.
See bot accounts documentation to learn more about how to create and manage bot accounts in Mattermost.
Deployments that cannot create bot accounts via webhooks due to security reasons and do not want to use personal access tokens with no expiry time, can use the following approach:
Create a bot account using a secure email and strong password.
Manually add the account to all teams and channels it needs access to. If your deployment has a lot of teams or channels, you may create a CLI script to automate the process.
Provide the email and password to your integration, and store it in a secure location with restricted access.
Have your integration use the email and password with an `/api/v4/login` endpoint to retrieve a session token. The session token is used to authenticate to the Mattermost system.
Set up your bot to make an HTTP POST to your-mattermost-url.com/api/v4/users/login with a JSON body, including the bot account’s email and password.
POST /api/v4/users/login HTTP/1.1
Host: your-mattermost-url.com
Content-Length: 66
Content-Type: application/json
{"login_id":"someone@nowhere.com","password":"thisisabadpassword"}
where we assume there is a Mattermost instance running at http://localhost:8065.
If successful, the response will contain a Token header and a user object in the body:
HTTP/1.1 200 OK
Set-Cookie: MMSID=hyr5dmb1mbb49c44qmx4whniso; Path=/; Max-Age=2592000; HttpOnly
Token: hyr5dmb1mbb49c44qmx4whniso
X-Ratelimit-Limit: 10
X-Ratelimit-Remaining: 9
X-Ratelimit-Reset: 1
X-Request-Id: smda55ckcfy89b6tia58shk5fh
X-Version-Id: developer
Date: Fri, 11 Sep 2015 13:21:14 GMT
Content-Length: 657
Content-Type: application/json; charset=utf-8
{{user object as json}}
The bot should retrieve the session token from the Token header and store it in memory for use with future requests.
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.
GET /api/v4/users/me HTTP/1.1
Authorization: bearer <yourtokenhere>
Host: your-mattermost-url.com
Automate Mattermost installation within another application:
/opt/mattermost directory by decompressing the tar.gz file of the latest release for your target platform (for example linux-amd64).config.json and set your automation to customize your Mattermost deployment based on your requirements.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.
/mattermost../bin/mattermost -version to test that the command line interface is functioning properly.Automate Mattermost upgrade within another application:
config.json file to preserve any settings a user may have made../data directory if local storage is used for files./mattermost directory with the decompressed contents of the latest release.config.json and ./data to their previous locations (which may have been overwritten).config.json parameters use a `sed` command or similar tool to update config.jsonconfig.json file, and ./data as necessary.Come join our Contributors community channel on our daily build server, where you can discuss questions with community members and the Mattermost core team. Join our Developers channel for technical discussions and our Integrations channel for all integrations and plugins discussions.