Event Notifications

Event notifications are arbitrary, non-secret data that can be exchanged between producers (Vault and plugins) and subscribers (Vault components and external users via the API).

Event types

Internal components of Vault as well as external plugins can generate event notifications. These are published to "event types", sometimes called "topics" in other event systems. All event notifications of a specific event type will have the same format for their additional metadata field.

The following event types are currently generated by Vault and its builtin plugins automatically:

Event notifications format

Event notifications may be formatted in protobuf binary format or as JSON. See EventReceived in sdk/logical/event.proto in the relevant Vault version for the protobuf schema.

When formatted as JSON, the event notification conforms to the CloudEvents specification.

• id (string) - CloudEvents unique identifier for the event notification. The id is unique for each event notification, and event notifications with the same id represent the same event notification.

• source (string) - CloudEvents source, which is set to vault:// followed by the Raft node ID or the hostname of the host that generated the event notification.

• specversion (string) - The CloudEvents specification version this conforms to.

• type (string) - CloudEvents type this event notification corresponds to, which is currently always *.

• datacontenttype (string) - CloudEvents content type of the event notification, which is currently always application/json.

• time (string) - ISO 8601-formatted timestamp for when the event notificcation was generated.

• data (object) - Vault-specific data.

  • event (Event) - contains the event notification that happened.

    • id (string) - (repeat of the id parameter)

    • metadata (object) - arbitrary extra data customized for the event type.

  • event_type (string) - the event type that was published.

  • plugin_info (PluginInfo) - information about the plugin that generated the event, if applicable.

    • mount_class (string) - the class of plugin, e.g., secret, auth.

    • mount_accessor (string) - the unique ID of the mounted plugin.

    • mount_path (string) - the path that the plugin is mounted at.

    • plugin (string) - the name of the plugin, e.g., kv.

Here is an example event notification in JSON format:

{
  "id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
  "source": "vault://mycluster",
  "specversion": "1.0",
  "type": "*",
  "data": {
    "event": {
      "id": "a3be9fb1-b514-519f-5b25-b6f144a8c1ce",
      "metadata": {
        "current_version": "1",
        "data_path": "secret/data/foo",
        "modified": "true",
        "oldest_version": "0",
        "operation": "data-write",
        "path": "secret/data/foo"
      }
    },
    "event_type": "kv-v2/data-write",
    "plugin_info": {
      "mount_class": "secret",
      "mount_accessor": "kv_5dc4d18e",
      "mount_path": "secret/",
      "plugin": "kv"
    }
  },
  "datacontentype": "application/cloudevents",
  "time": "2023-09-12T15:19:49.394915-07:00"
}

Subscribing to event notifications

Vault has an API endpoint, /v1/sys/events/subscribe/{eventType}, that allows users to subscribe to event notifications via a WebSocket stream. This endpoint supports the standard authentication and authorization workflows used by other Vault endpoints. The {eventType} parameter is a non-empty string of what event type to subscribe to, which may contain wildcards (*) to subscribe to multiple event types, e.g., kv-v2/data-*.

By default, the event notifications are delivered in protobuf binary format. The endpoint can also format the data as JSON if the json query parameter is set to true:

$ wscat -H "X-Vault-Token: $(vault print token)" --connect 'ws://127.0.0.1:8200/v1/sys/events/subscribe/kv-v2/data-write?json=true'
{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"vault://mycluster","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07:00"}
...

The Vault CLI support this endpoint via the events subscribe command, which will output a stream of JSON for the requested event notifications (one line per event notification):

$ vault events subscribe kv-v2/data-write
{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","source":"vault://mycluster","specversion":"1.0","type":"*","data":{"event":{"id":"a3be9fb1-b514-519f-5b25-b6f144a8c1ce","metadata":{"current_version":"1","data_path":"secret/data/foo","modified":"true","oldest_version":"0","operation":"data-write","path":"secret/data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_5dc4d18e","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-09-12T15:19:49.394915-07:00"}
...

Policies

To subscribe to an event notification, you must have the following policy grants:

1. read capability on /v1/sys/events/subscribe/{eventType}, where {eventType} is the event type that will be subscribed to. The path may contain wildcards.

   An example blanket policy is:

   path "sys/events/subscribe/*" {
       capabilities = ["read"]
   }
   

   Copy

2. list and subscribe capabilities on the path of the secret for events related to secrets. The policy must also provide a subscribe_event_types entry with the specific event notifications subscribers are allowed to use. For example, to receive event notifications related to the KV secrets engine path, secret/my-data, a valid policy would be:

   path "secret/my-data" {
     capabilities = ["list", "subscribe"]
     subscribe_event_types = ["*"]
   }
   

   Copy

Vault continuously evaluates policies for WebSocket subscriptions and caches the results for a short period of time to improve performance. As a result, event notifications may still be sent for a few minutes after a token is revoked or a policy is deleted.

Supported versions

For versions where event notifications are disabled by default, you can enable the functionality with the events.alpha1 experiment option in your Vault configuration or from the command line with the -experiments flag. For example:

$ vault server -experiment events.alpha1