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.
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
When the external integration sends a HTTP POST
request to this endpoint, your App will receive the request at the endpoint /webhook/my-sub-path
. The same webhook URL can be used to process HTTP HEAD
requests, in case the external integration requires this for webhook validation. The /my-sub-path
part of the above URL is optional, and it can be defined as any string value.
The App manifest contains an optional property on_remote_webhook
which defines the base call for incoming App webhooks.
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:
If the on_remote_webhook
call path 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
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
If the on_remote_webhook
call path 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
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
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": {}
}
}
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.
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
An example of implementing App webhooks can be found in the Mattermost apps examples repo.