diff options
Diffstat (limited to 'doc/integrations/webhooks/Incoming-Webhooks.md')
-rw-r--r-- | doc/integrations/webhooks/Incoming-Webhooks.md | 31 |
1 files changed, 20 insertions, 11 deletions
diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md index b5ae0fde2..7373892ad 100644 --- a/doc/integrations/webhooks/Incoming-Webhooks.md +++ b/doc/integrations/webhooks/Incoming-Webhooks.md @@ -1,6 +1,6 @@ # Incoming Webhooks -Incoming webhooks allow external applications, written in the programming language of your choice--to post messages into Mattermost channels and private groups by sending a specifically formatted JSON payload via HTTP POST request to a secret Mattermost URL generated specifically for each application. +Incoming webhooks allow external applications, written in the programming language of your choice--to post messages into Mattermost channels, private groups and direct messages by sending a specifically formatted JSON payload via HTTP POST request to a secret Mattermost URL generated specifically for each application. A couple key points: @@ -69,7 +69,7 @@ Additional Notes: 1. For the HTTP request body, if `Content-Type` is specified as `application/json` in the headers of the HTTP request then the body of the request can be direct JSON. For example, ```{"text": "Hello, this is some text."}``` -2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL +2. You can override the channel specified in the webhook definition by specifying a `channel` parameter in your payload. For example, you might have a single webhook created for _Town Square_, but you can use ```payload={"channel": "off-topic", "text": "Hello, this is some text."}``` to send a message to the _Off-Topic_ channel using the same webhook URL. If an `@` symbol followed by a username is specified, then the message will be sent to that user's direct message channel 1. In addition, with **Enable Overriding of Usernames from Webhooks** turned on, you can also override the username the message posts as by providing a `username` parameter in your JSON payload. For example, you might want your message looking like it came from a robot so you can use ```payload={"username": "robot", "text": "Hello, this is some text."}``` to change the username of the post to robot. Note, to combat any malicious users from trying to use this to perform [phishing attacks](https://en.wikipedia.org/wiki/Phishing) a `BOT` indicator appears next to posts coming from webhooks @@ -81,18 +81,27 @@ Additional Notes: ### Slack Compatibility -As mentioned above, Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. The following automatic translations are supported: +Mattermost makes it easy to take integrations written for Slack's proprietary JSON payload format and repurpose them to become Mattermost integrations. For example: + +#### Connecting Mattermost to GitLab using Slack UI + +GitLab is the leading open-source alternative to GitHub and offers built-in integrations with Slack. Rather than having to change code to support Mattermost, users can add Mattermost webhooks directly into the interface for Slack. + +1. In GitLab, go to **Settings** > **Services** and select **Slack**. +2. Paste in the incoming webhook URL provided by Mattermost from under **Account Settings** > **Integration** > **Incoming Webhooks**. +3. Optionally set the **Username** you'd like displayed when the notification is made. Leave the **Channel** field blank +4. Click **Save** then test the settings to confirm posts will be made to Mattermost + +#### Translating Slack's proprietary data format to Mattermost + +The following describes the automatic translations Mattermost performance to process data coming from Slack: 1. Payloads designed for Slack using `<>` to note the need to hyperlink a URL, such as ```payload={"text": "<http://www.mattermost.com/>"}```, are translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack 2. Similiarly, payloads designed for Slack using `|` within a `<>` to define linked text, such as ```payload={"text": "Click <http://www.mattermost.com/|here> for a link."}```, are also translated to the equivalent markdown in Mattermost and rendered the same as you would see in Slack -3. Like Slack, by overriding the channel name with an @username, such as payload={"text": "Hi", channel: "@jim"}, you can send the message to a user through your direct message chat -4. Channel names can be prepended with a #, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel +3. Like Slack, by overriding the channel name with a `@username`, such as `payload={"text": "Hi", channel: "@jim"}`, you can send the message to a user through your direct message chat +4. Channel names can be prepended with a `#`, like they are in Slack incoming webhooks, and the message will still be sent to the correct channel To see samples and community contributions, please visit <http://mattermost.org/webhooks>. -#### Known Issues in v1.1 - -- The `attachments` payload used in Slack is not yet supported -- Overriding of usernames does not yet apply to notifications (fixed on master) -- Cannot supply `icon_emoji` to override the message icon -- Webhook UI fails when connected to deleted channel (fixed on master) +#### Known Issues +- Mattermost does not yet support Slack's feature of using _icon_emoji_ to override the message icon. |