--- layout: docs page_title: Event Notications description: >- Event notifications allow Vault and plugins to exchange arbitrary activity data within Vault and with external subscribers via WebSockets. --- # Event Notifications @include 'alerts/enterprise-only.mdx' 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: | Plugin | Event Type | Metadata | Vault version | |----------|-------------------------------------|------------------------------------------------|---------------| | database | `database/config-delete` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/config-write` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/creds-create` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/reload` | `modified`, `operation`, `path`, `plugin_name` | 1.16 | | database | `database/reset` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/role-create` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/role-delete` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/role-update` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/root-rotate-fail` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/root-rotate` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/rotate-fail` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/rotate` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/static-creds-create-fail` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/static-creds-create` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/static-role-create` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/static-role-delete` | `modified`, `operation`, `path`, `name` | 1.16 | | database | `database/static-role-update` | `modified`, `operation`, `path`, `name` | 1.16 | | kv | `kv-v1/delete` | `modified`, `operation`, `path` | 1.13 | | kv | `kv-v1/write` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/config-write` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/data-delete` | `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/data-patch` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/data-write` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/delete` | `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/destroy` | `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/metadata-delete` | `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/metadata-patch` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/metadata-write` | `data_path`, `modified`, `operation`, `path` | 1.13 | | kv | `kv-v2/undelete` | `data_path`, `modified`, `operation`, `path` | 1.13 | ## Event notifications format Event notifications may be formatted in protobuf binary format or as JSON. See `EventReceived` in [`sdk/logical/event.proto`](https://github.com/hashicorp/vault/blob/main/sdk/logical/event.proto) in the relevant Vault version for the protobuf schema. When formatted as JSON, the event notification conforms to the [CloudEvents](https://cloudevents.io/) 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: ```json { "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`: ```shell-session $ 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): ```shell-session $ 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: ```hcl path "sys/events/subscribe/*" { capabilities = ["read"] } ``` 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: ```hcl path "secret/my-data" { capabilities = ["list", "subscribe"] subscribe_event_types = ["*"] } ``` 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 | Version | Support | |---------|---------------------------------------------| | <= 1.12 | Not supported | | 1.13 | Supported; **disabled** by default | | 1.14 | Supported; **disabled** by default | | 1.15 | Supported (beta); **enabled** by default | | 1.16+ | Generally available; **enabled** by default | For versions where event notifications are disabled by default, you can enable the functionality with the `events.alpha1` [experiment option](/vault/docs/configuration#experiments) in your Vault configuration or from the command line with the `-experiments` flag. For example: ```shell-session $ vault server -experiment events.alpha1 ```