Started outgoing webhook doc

2 files changed, 97 insertions, 3 deletions

diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md
index 7340282be..65a7953d5 100644
--- a/doc/integrations/webhooks/Incoming-Webhooks.md
+++ b/doc/integrations/webhooks/Incoming-Webhooks.md
@@ -4,8 +4,8 @@ Incoming webhooks allow external applications, written in the programming langua
 
 A couple key points:
 
-- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's propretiary JSON payload format into markdown to render in Mattermost messages.
-- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, incuding headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown].
+- **Mattermost incoming webhooks are Slack-compatible.** If you've used Slack's incoming webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages.
+- **Mattermost incoming webhooks support full markdown.** A rich range of formatting unavailable in Slack is made possible through [markdown support](../../usage/Markdown.md) in Mattermost, including headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown].
 
 _Example:_
 
@@ -63,7 +63,7 @@ curl -i -X POST -d 'payload={"text": "Hello, this is some text."}' http://yourma
 3. Build your integration in the programming language of your choice
  1. Most integrations will be used to translate some sort of output from another system to an appropriately formatted input that will be passed into the Mattermost webhook URL. For example, an integration could take events generated by [GitLab outgoing webhooks](http://doc.gitlab.com/ee/web_hooks/web_hooks.html) and parse them into a JSON body to post into Mattermost.
  1. To get the message posted into Mattermost, your integration will need to create an HTTP POST request that will submit to the incoming webhook URL you created before. The body of the request must have a `payload` that contains a JSON object that specifies a `text` parameter. For example, `payload={"text": "Hello, this is some text."}` is a valid body for a request.
- 2. Setup your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups.
+ 2. Set up your integration running on Heroku, an AWS server or a server of your own to start sending real time updates to Mattermost channels and private groups.
 
 Additional Notes:
 
diff --git a/doc/integrations/webhooks/Outgoing-Webhooks.md b/doc/integrations/webhooks/Outgoing-Webhooks.md
new file mode 100644
index 000000000..afe059e9f
--- /dev/null
+++ b/doc/integrations/webhooks/Outgoing-Webhooks.md
@@ -0,0 +1,94 @@
+# Outgoing Webhooks
+
+Outgoing webhooks allow external applications, written in the programming language of your choice--to receive HTTP POST requests whenever a user posts to a certain channel, with a trigger word at the beginning of the message, or a combination of both. If the external application responds appropriately to the HTTP request, as response post can be made in the channel where the original post occurred.
+
+A couple key points:
+
+- **Mattermost outgoing webhooks are Slack-compatible.** If you've used Slack's outgoing webhooks to create integrations, you can copy and paste that code to create Mattermost integrations. Mattermost automatically translates Slack's proprietary JSON payload format into markdown to render in Mattermost messages.
+- **Mattermost outgoing webhooks support full markdown.** When an integration responds with a message to post, it will have access to a rich range of formatting unavailable in Slack that is made possible through [markdown support](../../usage/Markdown.md) in Mattermost. This includes headings, formatted fonts, tables, inline images and other options supported by [Mattermost Markdown].
+
+_Example:_
+
+Suppose you had an external application that recieved a post event asking for the status of a daily build. The application could respond with a table of total tests run and total tests failed by component category, with links to failed tests by category. An example response the application could respond with would be:
+```
+{"text": "
+---
+##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
+| 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 a Mattermost message as follows:
+
+---
+##### Build Break - Project X - December 12, 2015 - 15:32 GMT +0
+| 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) |
+---
+
+### Enabling Outgoing Webhooks
+Outgoing webhooks should be enabled on your Mattermost instance by default, but if they are not you'll need to get your system administrator to enable them. If you are the system administrator you can enable them by doing the following:
+
+1. Login to your Mattermost team account that has the system administrator role.
+1. Enable outgoing webhooks from **System Console -> Service Settings**.
+1. (Optional) Configure the **Enable Overriding of Usernames from Webhooks** option to allow external applications to post messages under any name. If not enabled, the username of the creator of the webhook URL is used to post messages.
+2. (Optional) Configure the **Enable Overriding of Icon from Webhooks** option to allow external applciations to change the icon of the account posting messages. If not enabled, the icon of the creator of the webhook URL is used to post messages.
+
+### Set Up an Outgoing Webhook
+Once outgoing webhooks are enabled, you will be able to set one up through the Mattermost UI. You will need to know the following
+
+1. The channel (if not all of them) you want to listen to post events from
+2. The trigger words (if any) at the beginning of the post will trigger a post event
+3. The URL you want Mattermost to report the events to
+
+Once you have those, you can follow these steps to set up your webhook:
+
+1. Login to your Mattermost team site and go to **Account Settings -> Integrations**
+2. Next to **Outgoing Webhooks** click **Edit**
+3. Under **Add a new outgoing webhook** select your options
+ 1. Select a channel from the **Channel** dropdown to only report events from a certain channel (optional if Trigger Words selected)
+ 2. Enter comma separated words into **Trigger Words** to only report events from posts that start with one of those words (optional if **Channel** selected)
+ 3. Enter new line separated URLs that the post events will be sent too
+4. Click **Add** to add your webhook to the system
+5. Your new outgoing webhook will be displayed below with a **Token** that any external application that wants to listen to the webhook should ask for in it's instructions
+
+### Creating Integrations using Outgoing Webhooks
+
+If you'd like to build your own integration that uses outgoing webhooks, you can follow these general guidelines:
+
+1. In the programming language of your choice, write your integration to perform what you had in mind
+ 1. Your integration should have a function for receiving HTTP POSTs from Mattermost that look like this example:
+  ```
+    Content-Length: 244
+    User-Agent: Go 1.1 package http
+    Host: localhost:5000
+    Accept: application/json
+    Content-Type: application/x-www-form-urlencoded
+    Accept-Encoding: gzip
+
+    channel_id=hawos4dqtby53pd64o4a4cmeoo&
+    channel_name=town-square&
+    team_domain=someteam&
+    team_id=kwoknj9nwpypzgzy78wkw516qe&
+    text=some text here&
+    timestamp=1445532266&
+    token=zmigewsanbbsdf59xnmduzypjc&
+    trigger_word=some&
+    user_id=rnina9994bde8mua79zqcg5hmo&
+    user_name=somename
+  ```
+ 2. Your integration must have a configurable **MATTERMOST_TOKEN** variable that is the Token given to you when you set up the outgoing webhook in Mattermost as decribed in the previous section _Set Up an Outgoing Webhook_. This configurable **MATTERMOST_TOKEN** must match the token in the request body so your application can be sure the request came from Mattermost
+ 3. If you want your integration to post a message back to the same channel, it can respond to the HTTP POST request from Mattermost with a JSON response body similar to this example:
+  ```
+  {
+    "text": "This some response text."
+  }
+  ```
+2. Set up your integration running on Heroku, an AWS server or a server of your own to start getting real time post events from Mattermost channels