Webhooks

You can use webhooks to cause an action in another service in response to a push event in the repository. Webhooks are POST requests sent to a URL you define in Docker Hub.

Prerequisites#

For a personal repository, only the repository owner can create webhooks. Collaborators can't create webhooks.

For an organization repository, you must be an organization owner or editor, or a team member with admin permissions on the repository. For more details, see Organization teams.

To create a webhook using the Docker Hub API, authenticate with one of the following:

• A personal access token with delete permissions
• An organization access token with the scope-webhook-edit scope or higher

Create a webhook#

To create a webhook: 1. In your chosen repository, select the Webhooks tab. 2. Provide a name for the webhook. 3. Provide a destination webhook URL. This is where webhook POST requests are delivered. The URL must be 255 characters or fewer. 4. Select Create.

View webhook delivery history#

To view the history of the webhook: 1. Hover over your webhook under the Current Webhooks section. 2. Select the Menu options icon. 3. Select View History.

You can then view the delivery history, and whether delivering the POST request was successful or not.

Example webhook payload#

Webhook payloads have the following JSON format:

{
  "callback_url": "https://registry.hub.docker.com/u/svendowideit/testhook/hook/2141b5bi5i5b02bec211i4eeih0242eg11000a/",
  "push_data": {
    "pushed_at": 1417566161,
    "pusher": "trustedbuilder",
    "tag": "latest"
  },
  "repository": {
    "comment_count": 0,
    "date_created": 1417494799,
    "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\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"
  }
}

[!NOTE]

The callback_url field is a legacy field and is no longer supported.