Small refactor of webhooks docs

[ci skip]

doc/web_hooks/web_hooks.md

@@ -1,17 +1,21 @@
 # Webhooks
 
-_**Note:**
+>**Note:**
-Starting from GitLab 8.5:_
+Starting from GitLab 8.5:
+- the `repository` key is deprecated in favor of the `project` key
+- the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key
+- the `project.http_url` key is deprecated in favor of the `project.git_http_url` key
 
-- _the `repository` key is deprecated in favor of the `project` key_
+Project webhooks allow you to trigger a URL if for example new code is pushed or
-- _the `project.ssh_url` key is deprecated in favor of the `project.git_ssh_url` key_
+a new issue is created. You can configure webhooks to listen for specific events
-- _the `project.http_url` key is deprecated in favor of the `project.git_http_url` key_
+like pushes, issues or merge requests. GitLab will send a POST request with data
+to the webhook URL.
 
-Project webhooks allow you to trigger an URL if new code is pushed or a new issue is created.
+Webhooks can be used to update an external issue tracker, trigger CI builds,
+update a backup mirror, or even deploy to your production server.
 
-You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL.
+Navigate to the webhooks page by choosing **Webhooks** from your project's
-
+settings which can be found under the wheel icon in the upper right corner.
-Webhooks can be used to update an external issue tracker, trigger CI builds, update a backup mirror, or even deploy to your production server.
 
 ## Webhook endpoint tips
 
@@ -26,21 +30,27 @@ GitLab webhooks keep in mind the following things:
     you are writing a low-level hook this is important to remember.
 -   GitLab ignores the HTTP status code returned by your endpoint.
 
-## Secret Token
+## Secret token
 
-If you specify a secret token, it will be sent with the hook request in the `X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify that the request is legitimate.
+If you specify a secret token, it will be sent with the hook request in the
+`X-Gitlab-Token` HTTP header. Your webhook endpoint can check that to verify
+that the request is legitimate.
 
-## SSL Verification
+## SSL verification
 
 By default, the SSL certificate of the webhook endpoint is verified based on
-an internal list of Certificate Authorities,
+an internal list of Certificate Authorities, which means the certificate cannot
-which means the certificate cannot be self-signed.
+be self-signed.
 
 You can turn this off in the webhook settings in your GitLab projects.
 
 ![SSL Verification](ssl.png)
 
-## Push events
+## Events
+
+Below are described the supported events.
+
+### Push events
 
 Triggered when you push to the repository except when pushing tags.
 
@@ -121,7 +131,7 @@ X-Gitlab-Event: Push Hook
 }
 ```
 
-## Tag events
+### Tag events
 
 Triggered when you create (or delete) tags to the repository.
 
@@ -174,7 +184,7 @@ X-Gitlab-Event: Tag Push Hook
 }
 ```
 
-## Issues events
+### Issues events
 
 Triggered when a new issue is created or an existing issue was updated/closed/reopened.
 
@@ -240,7 +250,7 @@ X-Gitlab-Event: Issue Hook
   }
 }
 ```
-## Comment events
+### Comment events
 
 Triggered when a new comment is made on commits, merge requests, issues, and code snippets.
 The note data will be stored in `object_attributes` (e.g. `note`, `noteable_type`). The
@@ -253,7 +263,7 @@ Valid target types:
 3. `issue`
 4. `snippet`
 
-### Comment on commit
+#### Comment on commit
 
 **Request header**:
 
@@ -332,7 +342,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on merge request
+#### Comment on merge request
 
 **Request header**:
 
@@ -459,7 +469,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on issue
+#### Comment on issue
 
 **Request header**:
 
@@ -534,7 +544,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-### Comment on code snippet
+#### Comment on code snippet
 
 **Request header**:
 
@@ -607,7 +617,7 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-## Merge request events
+### Merge request events
 
 Triggered when a new merge request is created, an existing merge request was updated/merged/closed or a commit is added in the source branch.
 
@@ -699,7 +709,7 @@ X-Gitlab-Event: Merge Request Hook
 }
 ```
 
-## Wiki Page events
+### Wiki Page events
 
 Triggered when a wiki page is created or edited.
 
@@ -754,7 +764,7 @@ X-Gitlab-Event: Wiki Page Hook
 }
 ```
 
-## Pipeline events
+### Pipeline events
 
 Triggered on status change of Pipeline.
 
@@ -922,8 +932,7 @@ X-Gitlab-Event: Pipeline Hook
 }
 ```
 
-
+### Build events
-## Build events
 
 Triggered on status change of a Build.
 
@@ -935,7 +944,7 @@ X-Gitlab-Event: Build Hook
 
 **Request Body**:
 
-```
+```json
 {
   "object_kind": "build",
   "ref": "gitlab-script-trigger",
@@ -980,12 +989,13 @@ X-Gitlab-Event: Build Hook
 }
 ```
 
-#### Example webhook receiver
+## Example webhook receiver
 
 If you want to see GitLab's webhooks in action for testing purposes you can use
-a simple echo script running in a console session.
+a simple echo script running in a console session. For the following script to
+work you need to have Ruby installed.
 
-Save the following file as `print_http_body.rb`.
+Save the following file as `print_http_body.rb`:
 
 ```ruby
 require 'webrick'
@@ -1005,7 +1015,8 @@ Pick an unused port (e.g. 8000) and start the script: `ruby print_http_body.rb
 8000`.  Then add your server as a webhook receiver in GitLab as
 `http://my.host:8000/`.
 
-When you press 'Test Hook' in GitLab, you should see something like this in the console.
+When you press 'Test Hook' in GitLab, you should see something like this in the
+console:
 
 ```
 {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}