---
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

<!-- This information will probably be migrated to the plugin pages eventually -->

<Note title="Note">

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.

</Note>

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

<Note title="Note">

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.

</Note>

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
```
