---
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
Event types without the `path` metadata field require a root token in order to be consumed from the `/v1/sys/events/subscribe/{eventType}` API endpoint.
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/reload-connection` | `modified`, `operation`, `path`, `name` | 1.19 |
| database | `database/reload-connection-fail` | `modified`, `operation`, `path`, `name` | 1.19 |
| 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
For multi-node Vault deployments, Vault only accepts subscriptions on the active node and performance standbys.
Vault reroutes subscription requests made to [non-performance standby nodes](/vault/docs/enterprise/performance-standby#disabling-performance-standbys) to the active node based on the [`api_addr`](/vault/docs/configuration#api_addr) configuration setting on the active node.
Vault deployments with performance replication must subscribe to events on the
primary performance cluster. Vault ignores subscriptions made from secondary
clusters.
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
```