Events

Events are arbitrary, non-secret data that can be exchanged between producers (Vault and plugins) and subscribers (Vault components and external users via the API). Events are delivered on a best-effort basis, so do not have delivery guarantees at this time.

As of Vault 1.13, events are not considered production-ready, and so are disabled by default when starting a Vault server. Events can be enabled via the events.alpha1 experiment option in the Vault configuration or on the command-line:

$ vault server -experiment events.alpha1

Event types

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

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

Event format

Events 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 conforms to the CloudEvents specification.

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

• source (string) - CloudEvents source, which is currently https://vaultproject.io.

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

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

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

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

• data (object) - Vault-specific data.

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

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

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

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

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

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

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

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

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

Here is an example event in JSON format:

{
  "id": "901f2388-aabb-a385-7bc0-0b09d5fa060b",
  "source": "https://vaultproject.io/",
  "specversion": "1.0",
  "type": "*",
  "data": {
    "event": {
      "id": "901f2388-aabb-a385-7bc0-0b09d5fa060b",
      "metadata": {
        "current_version": "1",
        "oldest_version": "0",
        "path": "data/foo"
      }
    },
    "event_type": "kv-v2/data-write",
    "plugin_info": {
      "mount_class": "secret",
      "mount_accessor": "kv_a6081d01",
      "mount_path": "secret/",
      "plugin": "kv"
    }
  },
  "datacontentype": "application/cloudevents",
  "time": "2023-02-17T13:11:39.227341-08:00"
}

Subscribing to events

Vault has an API endpoint, /v1/sys/events/subscribe/{eventType}, that allows users to subscribe to events 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 events, e.g., kv-v2/data-*.

By default, the events 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 events (one line per event):

$ vault events subscribe kv-v2/data-write
{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","source":"https://vaultproject.io/","specversion":"1.0","type":"*","data":{"event":{"id":"901f2388-aabb-a385-7bc0-0b09d5fa060b","metadata":{"current_version":"1","oldest_version":"0","path":"data/foo"}},"event_type":"kv-v2/data-write","plugin_info":{"mount_class":"secret","mount_accessor":"kv_a6081d01","mount_path":"secret/","plugin":"kv"}},"datacontentype":"application/cloudevents","time":"2023-02-17T13:11:39.227341-08:00"}
...

Policies

To subscribe, the read capability must be granted by a policy on the /v1/sys/events/subscribe/{eventType} path, 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"]
}

Supported versions