Edit on GitHub

Outgoing webhooks

Create an outgoing webhook 

Suppose you want to write an external application, which executes software tests after someone posts a message starting with the word #build in the town-square channel.

You can follow these general guidelines to set up a Mattermost outgoing webhook for your application.

  1. First, go to Product menu > Integrations > Outgoing Webhook. If you don’t have the Integrations option available, outgoing webhooks may not be enabled on your Mattermost server or may be disabled for non-admins. Enable them from System Console > Integrations > Integration Management or ask your System Admin to do so.

  2. Select Add Outgoing Webhook and add name and description for the webhook. The description can be up to 500 characters.

  3. Choose the content type by which the request will be sent.

    • If application/x-www-form-urlencoded is chosen, the server will encode the parameters in a URL format in the request body.
    • If application/json is chosen, the server will format the request body as JSON.
  4. Select the public channel to receive webhook responses, or specify one or more trigger words that send an HTTP POST request to your application. You may configure either the channel or the trigger words for the outgoing webhook, or both. If both are specified, then the message must match both values.

    In our example, we would set the channel to town-square and specify #build as the trigger word.

  5. If you specified one or more trigger words on the previous step, choose when to trigger the outgoing webhook.

    • If the first word of a message matches one of the trigger words exactly, or
    • If the first word of a message starts with one of the trigger words.
  6. Finally, set one or more callback URLs that HTTP POST requests will be sent to, then select Save. If the URL is private, add it as a trusted internal connection.

  7. On the next page, copy the Token value. This will be used in a later step.

    Dialog box showing Setup Successful message and Token in the description message

Use an outgoing webhook 

  1. Include a function in your application which receives HTTP POST requests from Mattermost. The POST request should look something like this:

    POST /my-endpoint HTTP/1.1
    Content-Length: 244
    User-Agent: Go 1.1 package http
    Host: localhost:5000
    Accept: application/json
    Content-Type: application/x-www-form-urlencoded

    If your integration sends back a JSON response, make sure it returns the application/json content-type.

  2. Add a configurable MATTERMOST_TOKEN variable to your application and set it to the Token value from step 7. This value will be used by your application to confirm the HTTP POST request came from Mattermost.

  3. To have your application post a message back to town-square, it can respond to the HTTP POST request with a JSON response such as:

    {"text": "
    | Component  | Tests Run | Tests Failed                                   |
    | Server     | 948       | ✅ 0                           |
    | Web Client | 123       | ⚠️ [2 (see details)](http://linktologs) |
    | iOS Client | 78        | ⚠️ [3 (see details)](http://linktologs) |

    which would render in Mattermost as:

    Test results for Server, Web Client and iOS client

You’re all set!


Outgoing 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 other Mattermost messages.
If attachments is not set, yes
response_type Set to comment to reply to the message that triggered it.
Set to blank or post to create a regular message.
Defaults to post.
username Overrides the username the message posts as.
Defaults to the username set during webhook creation; if no username was set during creation, webhook is used.
The Enable integrations to override usernames configuration setting must be enabled for the username override to take effect.
icon_url Overrides the profile picture the message posts with.
Defaults to the URL set during webhook creation; if no icon was set during creation, the standard webhook icon () is displayed.
The Enable integrations to override profile picture icons configuration setting must be enabled for the icon override to take effect.
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_”.
Specifying a value for the attachments property will cause this field to be ignored, and the type value set to slack_attachment.
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.
priority Set the priority of the message. See Message Priority No

An example response using more parameters would look like this:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 755

  "response_type": "comment",
  "username": "test-automation",
  "icon_url": "https://mattermost.com/wp-content/uploads/2022/02/icon.png",
  "text": "\n#### Test results for July 27th, 2017\n@channel here are the requested test results.\n\n| Component  | Tests Run   | Tests Failed                                   |\n| ---------- | ----------- | ---------------------------------------------- |\n| Server     | 948         | ✅ 0                           |\n| Web Client | 123         | ⚠️ 2 [(see details)](http://linktologs) |\n| iOS Client | 78          | ⚠️ 3 [(see details)](http://linktologs) |\n\t\t      ",
  "props": {
    "test_data": {
    "server": 948,
    "web": 123,
    "ios": 78

The response would produce a message like the following:

test-automation bot showing test results

Messages with advanced formatting can be created by including an attachment array and interactive message buttons in the JSON payload.

Did you find what you were looking for?

Thank you! We appreciate your feedback.

Tell us more

Your feedback helps us improve the Mattermost developer documentation.

Have a feature request? Share it here.

Having issues? Join our Community server.