Webhook notifications

[dmp42]

We need quite soon an asynchronous way to notify (remote) third-party code that "events" are happening (pull, push start, push end? pretty much).

One use case is to notify the docker hub and index of events from the registry. Other use cases are enumerated in docker-archive/docker-registry#689, which is superseded by this issue.

Proposal

To implement this feature, we will notify listeners via http messages when a given event happens. Reliable, at-least-once delivery will be attempted until a 2xx response is received.

Notification listeners will be configured in the registry configuration file. Authenticity for a listener can be controlled by TLS certificates if an https endpoint is defined. The configuration may support other sinks besides http/https.

A summary of events in the initial version are the following:

• Manifest Pushed
• Manifest Pulled
• Manifest Deleted
• Blob Pushed
• Blob Pulled
• Blob Deleted

The following sections cover some of the proposed events and an example of what that data might look like. The protocol is subject to change and we are unlikely to lock it down for the beta release.

Actor and Source

The event notifications should include a source and actor, created from the request and authorization context of the request. The actor should indicate which authorized user initiated the event action and any request context (request id, etc.). The source should identify the registry system and node from which the event originated.

Registry Notification Types

Manifests

Manifest Pushed

• Name
• Tag
• Manifest Hash
• Current Time
• Account (If Known)

Example

{
    "name": "library/ubuntu",
    "tag": "14.04",
    "manifestHash": "sha256:2c39bdf1854ced6871b52452cbe8833edda34c7f299583567b400cecf2998837",
    "currentTime": "2015-01-13T00:15:28.469328",
    "url": "https://registry.docker.com/v2/library/ubuntu/manifests/14.04",
    "account": "tianon"
}

Manifest Pulled

• Name
• Tag
• Manifest Hash
• Current Time
• Account (If Known)

Example

{
    "name": "jlhawn/crawler-webserver",
    "tag": "v3.1.4-a159",
    "manifestHash": "sha256:941e74dc593fc8976122c316647048399fa0b490b858769739924eea5ea14334",
    "currentTime": "2015-01-13T00:18:05.236706",
    "url": "https://registry.docker.com/v2/jlhawn/crawler-webserver/manifests/v3.1.4-a159",
    "account": "samalba"
}

Manifest Deleted

• Name
• Tag
• Manifest Hash
• Current Time
• Account (If Known)

Example

{
    "name": "dmcgowan/fresh-baked-cookies",
    "tag": "chocolate-chip",
    "manifestHash": "sha256:4f98543ac6f792c1352e8c5a0555601ab3fd3497810581606c36c7416c5ffe37",
    "currentTime": "2015-01-13T00:18:54.781669",
    "url": "https://registry.docker.com/v2/dmcgowan/fresh-baked-cookies/manifests/chocolate-chip",
    "account": "dmcgowan"
}

Blobs

Blob Pushed (Upon conclusion)

• Name
• Blob Hash
• Current Time
• Account (If Known)

Example

{
    "name": "dmp42/portrait-landscape",
    "blobHash": "sha256:bb40a9ef6deed88cb1de6a50b6e2df6d301f52374805b98ca77b819b0f3ed3fa",
    "currentTime": "2015-01-13T00:21:58.110908",
    "url": "https://registry.docker.com/v2/dmp42/portrait-landscape/blobs/sha256%3Abb40a9ef6deed88cb1de6a50b6e2df6d301f52374805b98ca77b819b0f3ed3fa",
    "account": "goforgopher"
}

Blob Pulled (Upon conclusion)

• Name
• Blob Hash
• Current Time
• Account (If Known)

Example

{
    "name": "stevvooe/fresh-powder",
    "blobHash": "sha256:d712d5f15eda3abf569f3423714ad10d065d43421ad9efeeb9f6a1f6113ce0a8",
    "currentTime": "2015-01-13T00:23:15.083209",
    "url": "https://registry.docker.com/v2/stevvooe/fresh-powder/blobs/sha256%3Ad712d5f15eda3abf569f3423714ad10d065d43421ad9efeeb9f6a1f6113ce0a8",
    "account": "mikelipz"
}

Originally proposed by @jlhawn from https://gist.github.com/jlhawn/1c177252d343ae042e09.

[stevvooe]

First real event coming through after a push:

POST /_test HTTP/1.1
Host: localhost:8082
Accept-Encoding: gzip
Content-Type: application/vnd.docker.distribution.events.v1+json
User-Agent: Go 1.1 package http

{
   "events": [
      {
         "uuid": "60605ee7-e34e-4868-a2f3-34b039fa95ee",
         "timestamp": "2015-01-27T16:43:01.403566331-08:00",
         "action": "push",
         "target": {
            "type": "manifest",
            "name": "library/redis",
            "digest": "sha256:ca18155814ea932217da10270a95ed3f0eaeeeb2ffaa4aa08a0ec985367b83f7",
            "tag": "2",
            "url": "http://localhost:5000/v2/library/redis/manifests/2"
         },
         "actor": {
            "name": "--todo--",
            "addr": "127.0.0.1:58014"
         },
         "source": {
            "addr": "Stephens-MacBook-Pro.local:5000",
            "host": "example.com"
         }
      }
   ]
}

There are some problems to work out, but starting to get somewhere.

cc @jlhawn