Using Azure Container Registry webhooks

An Azure container registry stores and manages private Docker container images, similar to the way Docker Hub stores public Docker images. It can also host repositories for Helm charts (preview), a packaging format to deploy applications to Kubernetes. You can use webhooks to trigger events when certain actions take place in one of your registry repositories. Webhooks can respond to events at the registry level, or they can be scoped down to a specific repository tag. With a geo-replicated registry, you configure each webhook to respond to events in a specific regional replica.

The endpoint for a webhook must be publicly accessible from the registry. You can configure registry webhook requests to authenticate to a secured endpoint.

For details on webhook requests, see Azure Container Registry webhook schema reference.

Prerequisites

Create webhook - Azure portal

  1. Sign in to the Azure portal.
  2. Navigate to the container registry in which you want to create a webhook.
  3. Under Services, select Webhooks.
  4. Select Add in the webhook toolbar.
  5. Complete the Create webhook form with the following information:
Value Description
Webhook name The name you want to give to the webhook. It may contain only letters and numbers, and must be 5-50 characters in length.
Location For a geo-replicated registry, specify the Azure region of the registry replica.
Service URI The URI where the webhook should send POST notifications.
Custom headers Headers you want to pass along with the POST request. They should be in "key: value" format.
Trigger actions Actions that trigger the webhook. Actions include image push, image delete, Helm chart push, Helm chart delete, and image quarantine. You can choose one or more actions to trigger the webhook.
Status The status for the webhook after it's created. It's enabled by default.
Scope The scope at which the webhook works. If not specified, the scope is for all events in the registry. It can be specified for a repository or a tag by using the format "repository:tag", or "repository:*" for all tags under a repository.

Example webhook form:

Screenshot that shows the ACR webhook creation U I in the Azure portal.

Create webhook - Azure CLI

To create a webhook using the Azure CLI, use the az acr webhook create command. The following command creates a webhook for all image delete events in the registry mycontainerregistry:

az acr webhook create --registry mycontainerregistry --name myacrwebhook01 --actions delete --uri http://webhookuri.com

Test webhook

Azure portal

Prior to using the webhook, you can test it with the Ping button. Ping sends a generic POST request to the specified endpoint and logs the response. Using the ping feature can help you verify you've correctly configured the webhook.

  1. Select the webhook you want to test.
  2. In the top toolbar, select Ping.
  3. Check the endpoint's response in the HTTP STATUS column.

ACR webhook creation UI in the Azure portal

Azure CLI

To test an ACR webhook with the Azure CLI, use the az acr webhook ping command.

az acr webhook ping --registry mycontainerregistry --name myacrwebhook01

To see the results, use the az acr webhook list-events command.

az acr webhook list-events --registry mycontainerregistry08 --name myacrwebhook01

Delete webhook

Azure portal

Each webhook can be deleted by selecting the webhook and then the Delete button in the Azure portal.

Azure CLI

az acr webhook delete --registry mycontainerregistry --name myacrwebhook01

Next steps

Webhook schema reference

For details on the format and properties of the JSON event payloads emitted by Azure Container Registry, see the webhook schema reference:

Azure Container Registry webhook schema reference

Event Grid events

In addition to the native registry webhook events discussed in this article, Azure Container Registry can emit events to Event Grid:

Quickstart: Send container registry events to Event Grid