megaphone icon We're improving your developer experience.
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.

    Note: If you leave the channel field blank, the webhook will respond to trigger words in all public channels of your team. Similarly, if you don’t specify trigger words, then the webhook will respond to all messages in the selected public channel.

  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.

    image

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
    
    channel_id=hawos4dqtby53pd64o4a4cmeoo&
    channel_name=town-square&
    team_domain=someteam&
    team_id=kwoknj9nwpypzgzy78wkw516qe&
    post_id=axdygg1957njfe5pu38saikdho&
    text=some+text+here&
    timestamp=1445532266&
    token=zmigewsanbbsdf59xnmduzypjc&
    trigger_word=some&
    user_id=rnina9994bde8mua79zqcg5hmo&
    user_name=somename
    

    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         | :white_check_mark: 0                           |
    | Web Client | 123         | :warning: [2 (see details)](http://linktologs) |
    | iOS Client | 78          | :warning: [3 (see details)](http://linktologs) |
    "}
    

    which would render in Mattermost as:

    image

You’re all set!

Parameters 

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”.
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_”. Passing attachments will ignore this field and set the type to slack_attachment.
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 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         | :white_check_mark: 0                           |\n| Web Client | 123         | :warning: 2 [(see details)](http://linktologs) |\n| iOS Client | 78          | :warning: 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:

image

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

Note: Enable integrations to override usernames must be set to true in config.json to override usernames. Enable them from System Console > Integrations > Integration Management or ask your System Admin. If not enabled, the username is set to webhook.

Similarly, Enable integrations to override profile picture icons must be set to true in config.json to override usernames. Enable them from System Console > Integrations > Integration Management or ask your System Admin. If not enabled, the icon of the creator of the webhook URL is used to post messages.