Can Docker registry notifications serve as an audit trail?

Registry notifications can feed an audit trail, but they cannot be your only record. The registry sends events for pushes, pulls and deletes to a webhook with actor, request and source fields. The docs also say the queues are in memory and delivery is best effort, so events can be lost.

What an event contains

According to the Distribution notifications documentation, each event includes an id, timestamp and action, plus these groups.

• target: the digest, repository, size, url, tag and mediaType.
• request: the request id, client address, host, method and user agent.
• actor: the agent that started the event, usually taken from the request's authorization context.
• source: the registry node that produced the event, with its address and instance ID.

Events cover manifest and layer pushes and pulls, and deletes too. The page notes that delete events carry only the digest and repository in their target.

Configuring an endpoint

notifications:
  endpoints:
    - name: alistener
      url: https://mylistener.example.com/event
      headers:
        Authorization: [Bearer <token>]
      timeout: 500ms
      threshold: 5
      backoff: 1s

timeout limits each request, threshold is the number of consecutive failures before the registry backs off, and backoff is the wait before retrying. Any 2xx or 3xx response after redirects counts as delivered. Events go to each endpoint one after another, but order is not guaranteed.

The limits that matter

• Queues are in memory and delivery is best effort. If the registry instance stops before your endpoint recovers, messages can be lost.
• Order is not guaranteed, so do not rebuild a timeline from arrival order. Sort by timestamp.
• The docs example shows an empty actor, so actor data may be missing in some setups. With no authentication, there is nobody to name.
• Delete events carry less detail than pushes.

None of that makes the feature useless. It makes it a good alert source and a supplement to logs, not a legal record.

A layered approach

Use more than one. The pairing of a notification stream with the raw access log lets you notice gaps, because a push in the log with no matching event shows you lost something.

Steps

1. Run the listener close to the registry, or one that writes to disk before forwarding, as the docs suggest.
2. Store events somewhere append only, with a retention period set by policy.
3. Alert on deletes and on pushes to protected repositories from unexpected actors.
4. Watch queue health at the debug variables endpoint, where pending and failure counts appear.
5. Test by pushing an image and confirming the event arrives with the fields you need.

If you want to know what is inside the images that these events describe, Safeguard can scan them and produce an SBOM, with a free scan at gold.safeguard.sh/scan.

Quick check

Sources

• Notifications, Distribution docs
• Registry configuration reference

Last reviewed: 19 October 2026.