Azure Container Registry webhook reference

You can configure webhooks for your container registry that generate events when certain actions are performed against it. For example, enable webhooks that are triggered when a container image or Helm chart is pushed to a registry, or deleted. When a webhook is triggered, Azure Container Registry issues an HTTP or HTTPS request containing information about the event to an endpoint you specify. Your endpoint can then process the webhook and act accordingly.

The following sections detail the schema of webhook requests generated by supported events. The event sections contain the payload schema for the event type, an example request payload, and one or more example commands that would trigger the webhook.

For information about configuring webhooks for your Azure container registry, see Using Azure Container Registry webhooks.

Webhook requests

HTTP request

A triggered webhook makes an HTTP POST request to the URL endpoint you specified when you configured the webhook.

HTTP headers

Webhook requests include a Content-Type of application/json if you have not specified a Content-Type custom header for your webhook.

No other headers are added to the request beyond those custom headers you might have specified for the webhook.

Push event

Webhook triggered when a container image is pushed to a repository.

Push event payload

Element	Type	Description
id	String	The ID of the webhook event.
timestamp	DateTime	The time at which the webhook event was triggered.
action	String	The action that triggered the webhook event.
target	Complex Type	The target of the event that triggered the webhook event.
request	Complex Type	The request that generated the webhook event.

target

Element	Type	Description
mediaType	String	The MIME type of the referenced object.
size	Int32	The number of bytes of the content. Same as Length field.
digest	String	The digest of the content, as defined by the Registry V2 HTTP API Specification.
length	Int32	The number of bytes of the content. Same as Size field.
repository	String	The repository name.
tag	String	The image tag name.

request

Element	Type	Description
id	String	The ID of the request that initiated the event.
host	String	The externally accessible hostname of the registry instance, as specified by the HTTP host header on incoming requests.
method	String	The request method that generated the event.
useragent	String	The user agent header of the request.

Payload example: image push event

{
  "id": "cb8c3971-9adc-488b-xxxx-43cbb4974ff5",
  "timestamp": "2017-11-17T16:52:01.343145347Z",
  "action": "push",
  "target": {
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "size": 524,
    "digest": "sha256:xxxxd5c8786bb9e621a45ece0dbxxxx1cdc624ad20da9fe62e9d25490f33xxxx",
    "length": 524,
    "repository": "hello-world",
    "tag": "v1"
  },
  "request": {
    "id": "3cbb6949-7549-4fa1-xxxx-a6d5451dffc7",
    "host": "myregistry.azurecr.io",
    "method": "PUT",
    "useragent": "docker/17.09.0-ce go/go1.8.3 git-commit/afdb6d4 kernel/4.10.0-27-generic os/linux arch/amd64 UpstreamClient(Docker-Client/17.09.0-ce \\(linux\\))"
  }
}

Example Docker CLI command that triggers the image push event webhook:

docker push myregistry.azurecr.io/hello-world:v1

Chart push event

Webhook triggered when a Helm chart is pushed to a repository.

Chart push event payload

Element	Type	Description
id	String	The ID of the webhook event.
timestamp	DateTime	The time at which the webhook event was triggered.
action	String	The action that triggered the webhook event.
target	Complex Type	The target of the event that triggered the webhook event.

target

Element	Type	Description
mediaType	String	The MIME type of the referenced object.
size	Int32	The number of bytes of the content.
digest	String	The digest of the content, as defined by the Registry V2 HTTP API Specification.
repository	String	The repository name.
tag	String	The chart tag name.
name	String	The chart name.
version	String	The chart version.

Payload example: chart push event

{
  "id": "6356e9e0-627f-4fed-xxxx-d9059b5143ac",
  "timestamp": "2019-03-05T23:45:31.2614267Z",
  "action": "chart_push",
  "target": {
    "mediaType": "application/vnd.acr.helm.chart",
    "size": 25265,
    "digest": "sha256:xxxx8075264b5ba7c14c23672xxxx52ae6a3ebac1c47916e4efe19cd624dxxxx",
    "repository": "repo",
    "tag": "wordpress-5.4.0.tgz",
    "name": "wordpress",
    "version": "5.4.0.tgz"
  }
}

Example Azure CLI command that triggers the chart_push event webhook:

az acr helm push wordpress-5.4.0.tgz --name MyRegistry

Delete event

Webhook triggered when an image repository or manifest is deleted. Not triggered when a tag is deleted.

Delete event payload

Element	Type	Description
id	String	The ID of the webhook event.
timestamp	DateTime	The time at which the webhook event was triggered.
action	String	The action that triggered the webhook event.
target	Complex Type	The target of the event that triggered the webhook event.
request	Complex Type	The request that generated the webhook event.

target

Element	Type	Description
mediaType	String	The MIME type of the referenced object.
digest	String	The digest of the content, as defined by the Registry V2 HTTP API Specification.
repository	String	The repository name.

request

Element	Type	Description
id	String	The ID of the request that initiated the event.
host	String	The externally accessible hostname of the registry instance, as specified by the HTTP host header on incoming requests.
method	String	The request method that generated the event.
useragent	String	The user agent header of the request.

Payload example: image delete event

{
    "id": "afc359ce-df7f-4e32-xxxx-1ff8aa80927b",
    "timestamp": "2017-11-17T16:54:53.657764628Z",
    "action": "delete",
    "target": {
      "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
      "digest": "sha256:xxxxd5c8786bb9e621a45ece0dbxxxx1cdc624ad20da9fe62e9d25490f33xxxx",
      "repository": "hello-world"
    },
    "request": {
      "id": "3d78b540-ab61-4f75-xxxx-7ca9ecf559b3",
      "host": "myregistry.azurecr.io",
      "method": "DELETE",
      "useragent": "python-requests/2.18.4"
    }
  }

Example Azure CLI commands that trigger a delete event webhook:

# Delete repository
az acr repository delete --name MyRegistry --repository MyRepository

# Delete image
az acr repository delete --name MyRegistry --image MyRepository:MyTag

Chart delete event

Webhook triggered when a Helm chart or repository is deleted.

Chart delete event payload

Element	Type	Description
id	String	The ID of the webhook event.
timestamp	DateTime	The time at which the webhook event was triggered.
action	String	The action that triggered the webhook event.
target	Complex Type	The target of the event that triggered the webhook event.

target

Element	Type	Description
mediaType	String	The MIME type of the referenced object.
size	Int32	The number of bytes of the content.
digest	String	The digest of the content, as defined by the Registry V2 HTTP API Specification.
repository	String	The repository name.
tag	String	The chart tag name.
name	String	The chart name.
version	String	The chart version.

Payload example: chart delete event

{
  "id": "338a3ef7-ad68-4128-xxxx-fdd3af8e8f67",
  "timestamp": "2019-03-06T00:10:48.1270754Z",
  "action": "chart_delete",
  "target": {
    "mediaType": "application/vnd.acr.helm.chart",
    "size": 25265,
    "digest": "sha256:xxxx8075264b5ba7c14c23672xxxx52ae6a3ebac1c47916e4efe19cd624dxxxx",
    "repository": "repo",
    "tag": "wordpress-5.4.0.tgz",
    "name": "wordpress",
    "version": "5.4.0.tgz"
  }
}

Example Azure CLI command that triggers the chart_delete event webhook:

az acr helm delete wordpress --version 5.4.0 --name MyRegistry

Next steps

Using Azure Container Registry webhooks