Mattermost Logo

Incoming Webhooks

Incoming webhooks let you POST some data to a Mattermost endpoint to create a message in a channel.

Basic Usage

Follow the admin guide to create the webhook endpoint. It’ll look something like this:

https://your-mattermost-server.com/hooks/xxx-generatedkey-xxx

Treat this endpoint as a secret. Anyone who has it will be able to post messages to your Mattermost instance.

To use the endpoint, have your application make the following request:

POST /hooks/xxx-generatedkey-xxx HTTP/1.1
Host: your-mattermost-server
Content-Type: application/json
Content-Length: 63

{"text": "Hello, this is some text\nThis is more text. :tada:"}

As a curl:

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

For compatibility with Slack incoming webhooks, if no Content-Type header is set then the request body must be prefixed with payload=, like so:

payload={"text": "Hello, this is some text\nThis is more text. :tada:"}

A successful request will get the following response:

HTTP/1.1 200 OK
Content-Type: text/plain
X-Request-Id: hoan6o9ws7rp5xj7wu9rmysrte
X-Version-Id: 4.7.1.dev.12799cd77e172e8a2eba0f9091ec1471.false
Date: Sun, 04 Mar 2018 17:19:09 GMT
Content-Length: 2

ok

All webhook posts will display a BOT indicator next to the username in Mattermost clients, to help prevent against phishing attacks.

Parameters

Incoming webhooks support more than just the text field. Here is a full list of supported parameters.

Parameter Description Required
text Markdown-formatted message to display in the post.
To trigger notifications, use @<username>, @channel and @here like you would in normal Mattermost messaging.
If attachments is not set, yes
channel Overrides the channel the message posts in. Use the channel’s name and not the display name, e.g. use town-square, not Town Square.
Use an “@” followed by a username to send to a direct message.
Defaults to the channel set during webhook creation.
The webhook can post to any public channel and private channel the webhook creator is in.
Posts to direct messages will appear in the DM between the targeted user and the webhook creator.
No
username Overrides the username the message posts as.
Defaults to the username set during webhook creation or the webhook creator’s username if the former was not set.
Must be enabled in the configuration.
No
icon_url Overrides the profile picture the message posts with.
Defaults to the URL set during webhook creation or the webhook creator’s profile picture if the former was not set.
Must be enabled in the configuration.
No
attachments Message attachments used for richer formatting options. If text is not set, yes
type Sets the post type, mainly for use by plugins.
If not blank, must begin with “custom_”.
No
props Sets the post props, a JSON property bag for storing extra or meta data on the post.
Mainly used by other integrations accessing posts through the REST API.
The following keys are reserved: “from_webhook”, “override_username”, “override_icon_url”, “webhook_display_name” and “attachments”.
No

An example request using some more parameters would look like this:

POST /hooks/xxx-generatedkey-xxx HTTP/1.1
Host: your-mattermost-server
Content-Type: application/json
Content-Length: 630

{
  "channel": "town-square",
  "username": "test-automation",
  "icon_url": "https://www.mattermost.org/wp-content/uploads/2016/04/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)](http://linktologs) |\n| iOS Client | 78          | :warning: 3 [(see details)](http://linktologs) |"
}

Slack Compatibility

See the admin guide’s notes on Slack compatibility.

Tips and Best Practices

  1. If the text is longer than the allowable character limit per post, the message is split into multiple consecutive posts, each within the character limit. Servers running Mattermost Server v5.0 or later can support posts up to 16383 characters.
  2. Your webhook integration may be written in any programming language as long as it supports sending an HTTP POST request.
  3. Both application/x-www-form-urlencoded and multipart/form-data are supported Content-Type headers. If no Content-Type is provided, application/json is assumed.