megaphone icon Learn how to streamline incident response with Mattermost & ServiceNow on February 16th ยป
Edit on GitHub

App webhooks

The Apps framework offers the ability to directly integrate with webhooks. An App webhook is executed through a special endpoint on the Mattermost Server and can require an authentication secret. The App manifest must request the remote_webhooks permission to use webhooks.

Webhook URL 

The App webhook URL has the following format:

<mattermost_site_url>/plugins/com.mattermost.apps/apps/<app_id>/webhook/<sub_path>?secret=<authentication_secret>
Parameter name Description Example value
mattermost_site_url The base URL of the Mattermost server. https://my-mattermost-server/
app_id The App’s ID as found in the manifest. my-app
sub_path (Optional) The webhook sub-path. See the Webhook call path section for more information. my-sub-path
authentication_secret The webhook secret; used to authenticate the webhook request. See Authentication for more information. cwsjhrdqebyf8qrnabtxio7k7r

Using the above example values, the webhook URL will look like this:

https://my-mattermost-server/plugins/com.mattermost.apps/apps/my-app/webhook/my-sub-path?secret=cwsjhrdqebyf8qrnabtxio7k7r

Webhook call path 

The App manifest contains an optional property on_remote_webhook which defines the base call path for incoming App webhooks. This property only affects the call path in the App; it does not affect the URL that an end user or system uses to execute the webhook.

The sub_path of a webhook URL is also optional. When it is defined, the call that is executed changes; the call path will be different.

Examples:

  1. If on_remote_webhook is not defined in the manifest and sub_path is also not defined, the call path will be /webhook and the webhook URL will be:

    <mattermost_site_url>/plugins/com.mattermost.apps/apps/<app_id>/webhook
    
  2. If the on_remote_webhook call path is defined as /my-webhooks in the manifest but sub_path is not defined, the call path will be /my-webhooks and the webhook URL will be:

    <mattermost_site_url>/plugins/com.mattermost.apps/apps/<app_id>/webhook
    
  3. If on_remote_webhook is not defined in the manifest but sub_path is defined as my-sub-path, the call path will be /webhook/my-sub-path and the webhook URL will be:

    <mattermost_site_url>/plugins/com.mattermost.apps/apps/<app_id>/webhook/my-sub-path
    
  4. If the on_remote_webhook call path is defined as /my-webhooks in the manifest and the sub_path is defined as my-sub-path, the call path will be /my-webhooks/my-sub-path and the webhook URL will be:

    <mattermost_site_url>/plugins/com.mattermost.apps/apps/<app_id>/webhook/my-sub-path
    

Call request 

The call executed for an App webhook will include additional information in the values field of the request:

Name Data type Description
headers map The HTTP headers used in the request.
data any The contents of the call request body.
JSON bodies are automatically unmarshalled, otherwise the body is returned as-is.
httpMethod string The HTTP method used in the request. e.g. POST, GET.
rawQuery string Encoded URL query values, without the ?.

An example webhook call request looks like the following:

POST /webhook HTTP/1.1
Content-Type: application/json

{
    "path": "/webhook",
    "values": {
        "data": "",
        "headers": {
            "Accept": "*/*",
            "Accept-Encoding": "gzip, deflate, br",
            "Connection": "keep-alive",
            "Content-Length": "0",
            "Mattermost-Session-Id": "",
            "User-Agent": "PostmanRuntime/7.30.0"
        },
        "httpMethod": "POST",
        "rawQuery": "secret=pszhs89rspyrje41khqouwbhce"
    },
    "context": {
        "acting_user_id": "mgbd1czngjbbdx6eqruqabdeie",
        "app_id": "hello-world",
        "mattermost_site_url": "http://mattermost:8066",
        "developer_mode": true,
        "app_path": "/plugins/com.mattermost.apps/apps/hello-world",
        "bot_user_id": "mgbd1czngjbbdx6eqruqabdeie",
        "bot_access_token": "nr7ne5p8oprkimkmt7xra67xjy",
        "acting_user_access_token": "nr7ne5p8oprkimkmt7xra67xjy",
        "oauth2": {}
    }
}

Authentication 

App webhooks support an API key-like authentication method that is enabled by default. A Mattermost server-generated secret named webhook_secret is provided in a call context where the app expand field is set to all. The secret is expected to be appended to the webhook URL as a query value named secret.

Using the example from the previous section, the webhook URL will look like this:

http://my-mattermost-server/plugins/com.mattermost.apps/apps/my-app/webhook/my-sub-path?secret=cwsjhrdqebyf8qrnabtxio7k7r

The Mattermost server will authenticate incoming webhook requests by comparing the secret URL query value with the App’s webhook_secret. If an incoming webhook request does not include the correct secret, the request will be denied with an HTTP 401 response.

Get the webhook secret 

A simple way to get the App’s webhook secret is to use a slash command that executes a call with the app expand field set to all.

For example, the following bindings create a slash command that will provide the webhook secret to its call:

[
    {
        "location": "/command",
        "bindings": [
            {
                "location": "configure",
                "label": "configure",
                "description": "Configure the app",
                "submit": {
                    "path": "/configure",
                    "expand": {
                        "app": "all"
                    }
                }
            }
        ]
    }
]

The call request would look like this:

{
    "path": "/configure",
    "expand": {
        "app": "all"
    },
    "context": {
        "app_id": "hello-world",
        "location": "/command/configure",
        "user_agent": "webapp",
        "track_as_submit": true,
        "mattermost_site_url": "http://mattermost:8066",
        "developer_mode": true,
        "app_path": "/plugins/com.mattermost.apps/apps/hello-world",
        "bot_user_id": "mgbd1czngjbbdx6eqruqabdeie",
        "bot_access_token": "q8idzs7dspf8ugra9sb7dkgxwe",
        "app": {
            "app_id": "hello-world",
            "version": "0.1.0",
            "webhook_secret": "cwsjhrdqebyf8qrnabtxio7k7r",
            "bot_user_id": "mgbd1czngjbbdx6eqruqabdeie",
            "bot_username": "hello-world",
            "remote_oauth2": {}
        },
        "acting_user": {
            "id": "7q7kaakokfdsdycy3pr9ctkc5r"
            // additional fields omitted for brevity
        },
        "oauth2": {}
    },
    "raw_command": "/configure "
}

The webhook secret can be found in the context.app.webhook_secret field.

Using the webhook secret above, a webhook URL for an App would look like the following:

http://mattermost:8066/plugins/com.mattermost.apps/apps/hello-world/webhook/coffee-roast?secret=cwsjhrdqebyf8qrnabtxio7k7r

Example 

An example of implementing App webhooks can be found in the Mattermost apps examples repo.

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.