mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
Add some extra details to webhook docs
Update the webhook JSON payloads to real ones, and show there is a difference between an automated build webhook payload and a normal repo payload Docker-DCO-1.1-Signed-off-by: Sven Dowideit <SvenDowideit@docker.com> (github: SvenDowideit) Signed-off-by: Sven Dowideit <SvenDowideit@docker.com>
This commit is contained in:
Sven Dowideit
parent
8e59bda173
commit
b4b899264e
2 changed files with 107 additions and 62 deletions
|
|
@ -229,48 +229,91 @@ repo on the Docker Hub.
|
|||
### 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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:*
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue