Merge pull request #9518 from fredlf/post-1.3.2-docs-update-02-part2docs-1.3.3

Merge pull request #9464 from SvenDowideit/sven_tries_webhooks

3 files changed, 120 insertions, 65 deletions

diff --git a/docs/sources/docker-hub/builds.md b/docs/sources/docker-hub/builds.md
index 7bf8b27eb2..5d73e4aae9 100644
--- a/docs/sources/docker-hub/builds.md
+++ b/docs/sources/docker-hub/builds.md
@@ -209,7 +209,7 @@ repository's full description.The build process will look for a
 > rewritten the next time the Automated Build has been built. To make changes,
 > modify the `README.md` from the Git repository.
 
-### Build triggers
+## Remote Build triggers
 
 If you need a way to trigger Automated Builds outside of GitHub or Bitbucket,
 you can set up a build trigger. When you turn on the build trigger for an
@@ -219,6 +219,16 @@ This will trigger the Automated Build, much as with a GitHub webhook.
 Build triggers are available under the Settings menu of each Automated Build
 repo on the Docker Hub.
 
+![Build trigger screen](/docker-hub/hub-images/build-trigger.png)
+
+You can use `curl` to trigger a build:
+
+```
+$ curl --data "build=true" -X POST https://registry.hub.docker.com/u/svendowideit/testhook/trigger/be579c
+82-7c0e-11e4-81c4-0242ac110020/
+OK
+```
+
 > **Note:** 
 > You can only trigger one build at a time and no more than one
 > every five minutes. If you already have a build pending, or if you
@@ -226,53 +236,96 @@ repo on the Docker Hub.
 > To verify everything is working correctly, check the logs of last
 > ten triggers on the settings page .
 
-### Webhooks
+## Webhooks
 
 Automated Builds also include a Webhooks feature. Webhooks can be called
-after a successful repository push is made.
+after a successful repository push is made. This includes when a new tag is added
+to an existing image.
 
 The webhook call will generate a HTTP POST with the following JSON
 payload:
 
 ```
 {
-   "push_data":{
-      "pushed_at":1385141110,
-      "images":[
-         "imagehash1",
-         "imagehash2",
-         "imagehash3"
-      ],
-      "pusher":"username"
-   },
-   "repository":{
-      "status":"Active",
-      "description":"my docker repo that does cool things",
-      "is_automated":false,
-      "full_description":"This is my full description",
-      "repo_url":"https://registry.hub.docker.com/u/username/reponame/",
-      "owner":"username",
-      "is_official":false,
-      "is_private":false,
-      "name":"reponame",
-      "namespace":"username",
-      "star_count":1,
-      "comment_count":1,
-      "date_created":1370174400,
-      "dockerfile":"my full dockerfile is listed here",
-      "repo_name":"username/reponame"
-   }
+  "callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
+  "push_data": {
+    "images": [],
+    "pushed_at": 1.417566161e+09,
+    "pusher": "trustedbuilder"
+  },
+  "repository": {
+    "comment_count": 0,
+    "date_created": 1.417494799e+09,
+    "description": "",
+    "dockerfile": "#\n# BUILD\u0009\u0009docker build -t svendowideit/apt-cacher .\n# RUN\u0009\u0009docker run -d -p 3142:3142 -name apt-cacher-run apt-cacher\n#\n# and then you can run containers with:\n# \u0009\u0009docker run -t -i -rm -e http_proxy http://192.168.1.2:3142/ debian bash\n#\nFROM\u0009\u0009ubuntu\nMAINTAINER\u0009SvenDowideit@home.org.au\n\n\nVOLUME\u0009\u0009[\"/var/cache/apt-cacher-ng\"]\nRUN\u0009\u0009apt-get update ; apt-get install -yq apt-cacher-ng\n\nEXPOSE \u0009\u00093142\nCMD\u0009\u0009chmod 777 /var/cache/apt-cacher-ng ; /etc/init.d/apt-cacher-ng start ; tail -f /var/log/apt-cacher-ng/*\n",
+    "full_description": "Docker Hub based automated build from a GitHub repo",
+    "is_official": false,
+    "is_private": true,
+    "is_trusted": true,
+    "name": "testhook",
+    "namespace": "svendowideit",
+    "owner": "svendowideit",
+    "repo_name": "svendowideit/testhook",
+    "repo_url": "https://registry.hub.docker.com/u/svendowideit/testhook/",
+    "star_count": 0,
+    "status": "Active"
+  }
 }
 ```
 
-Webhooks are available under the Settings menu of each Automated
-Build's repo.
+Webhooks are available under the Settings menu of each Repository.
 
 > **Note:** If you want to test your webhook out we recommend using
 > a tool like [requestb.in](http://requestb.in/).
 
+### Webhook chains
+
+Webhook chains allow you to chain calls to multiple services. For example,
+you can use this to trigger a deployment of your container only after
+it has been successfully tested, then update a separate Changelog once the
+deployment is complete.
+After clicking the "Add webhook" button, simply add as many URLs as necessary
+in your chain.
+
+The first webhook in a chain will be called after a successful push. Subsequent
+URLs will be contacted after the callback has been validated.
+
+### Validating a callback
+
+In order to validate a callback in a webhook chain, you need to
+
+1. Retrieve the `callback_url` value in the request's JSON payload.
+1. Send a POST request to this URL containing a valid JSON body.
+
+> **Note**: A chain request will only be considered complete once the last
+> callback has been validated.
+
+To help you debug or simply view the results of your webhook(s),
+view the "History" of the webhook available on its settings page.
+
+### Callback JSON data
+
+The following parameters are recognized in callback data:
+
+* `state` (required): Accepted values are `success`, `failure` and `error`.
+  If the state isn't `success`, the webhook chain will be interrupted.
+* `description`: A string containing miscellaneous information that will be
+  available on the Docker Hub. Maximum 255 characters.
+* `context`: A string containing the context of the operation. Can be retrieved
+  from the Docker Hub. Maximum 100 characters.
+* `target_url`: The URL where the results of the operation can be found. Can be
+  retrieved on the Docker Hub.
+
+*Example callback payload:*
+
+    {
+      "state": "success",
+      "description": "387 tests PASSED",
+      "context": "Continuous integration by Acme CI",
+      "target_url": "http://ci.acme.com/results/afd339c1c3d27"
+    }
 
-### Repository links
+## Repository links
 
 Repository links are a way to associate one Automated Build with
 another. If one gets updated,the linking system triggers a rebuild
diff --git a/docs/sources/docker-hub/hub-images/build-trigger.png b/docs/sources/docker-hub/hub-images/build-trigger.png
new file mode 100644
index 0000000000..25597a27bd
--- /dev/null
+++ b/docs/sources/docker-hub/hub-images/build-trigger.png
diff --git a/docs/sources/docker-hub/repos.md b/docs/sources/docker-hub/repos.md
index d0c2faea19..0749c0814c 100644
--- a/docs/sources/docker-hub/repos.md
+++ b/docs/sources/docker-hub/repos.md
@@ -110,34 +110,31 @@ similar to the example shown below.
 
 *Example webhook JSON payload:*
 
-    {
-       "push_data":{
-          "pushed_at":1385141110,
-          "images":[
-             "imagehash1",
-             "imagehash2",
-             "imagehash3"
-          ],
-          "pusher":"username"
-       },
-       "repository":{
-          "status":"Active",
-          "description":"my docker repo that does cool things",
-          "is_automated":false,
-          "full_description":"This is my full description",
-          "repo_url":"https://registry.hub.docker.com/u/username/reponame/",
-          "owner":"username",
-          "is_official":false,
-          "is_private":false,
-          "name":"reponame",
-          "namespace":"username",
-          "star_count":1,
-          "comment_count":1,
-          "date_created":1370174400,
-          "dockerfile":"my full dockerfile is listed here",
-          "repo_name":"username/reponame"
-       }
-    }
+```
+{
+  "callback_url": "https://registry.hub.docker.com/u/svendowideit/busybox/hook/2141bc0cdec4hebec411i4c1g40242eg110020/",
+  "push_data": {
+    "images": [],
+    "pushed_at": 1.417566822e+09,
+    "pusher": "svendowideit"
+  },
+  "repository": {
+    "comment_count": 0,
+    "date_created": 1.417566665e+09,
+    "description": "",
+    "full_description": "webhook triggered from a 'docker push'",
+    "is_official": false,
+    "is_private": false,
+    "is_trusted": false,
+    "name": "busybox",
+    "namespace": "svendowideit",
+    "owner": "svendowideit",
+    "repo_name": "svendowideit/busybox",
+    "repo_url": "https://registry.hub.docker.com/u/svendowideit/busybox/",
+    "star_count": 0,
+    "status": "Active"
+}
+```
 
 Webhooks allow you to notify people, services and other applications of
 new updates to your images and repositories. To get started adding webhooks,
@@ -153,7 +150,8 @@ deployment is complete.
 After clicking the "Add webhook" button, simply add as many URLs as necessary
 in your chain.
 
-The first webhook in a chain will be called after a successful push. Subsequent URLs will be contacted after the callback has been validated.
+The first webhook in a chain will be called after a successful push. Subsequent
+URLs will be contacted after the callback has been validated.
 
 #### Validating a callback
 
@@ -172,10 +170,14 @@ view the "History" of the webhook available on its settings page.
 
 The following parameters are recognized in callback data:
 
-* `state` (required): Accepted values are `success`, `failure` and `error`. If the state isn't `success`, the webhook chain will be interrupted.
-* `description`: A string containing miscellaneous information that will be available on the Docker Hub. Maximum 255 characters.
-* `context`: A string containing the context of the operation. Can be retrieved on the Docker Hub. Maximum 100 characters.
-* `target_url`: The URL where the results of the operation can be found. Can be retrieved on the Docker Hub.
+* `state` (required): Accepted values are `success`, `failure` and `error`.
+  If the state isn't `success`, the webhook chain will be interrupted.
+* `description`: A string containing miscellaneous information that will be
+  available on the Docker Hub. Maximum 255 characters.
+* `context`: A string containing the context of the operation. Can be retrieved
+  from the Docker Hub. Maximum 100 characters.
+* `target_url`: The URL where the results of the operation can be found. Can be
+  retrieved on the Docker Hub.
 
 *Example callback payload:*