kms/docs/documentation/platform/event-subscriptions.mdx

---
title: "Event Subscriptions"
sidebarTitle: "Events Subscriptions"
description: "Subscribe to events in KMS for real-time updates"
---

<Note>
   Event Subscriptions is a paid feature that is available under the Enterprise license.
   Please contact [[email protected]](mailto:[email protected]).
</Note>

Event Subscriptions allow you to receive real-time notifications when specific actions occur within your KMS projects. You can subscribe to changes such as secret modifications, with support for additional resource types coming soon.

## How It Works

Event Subscriptions use [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) to deliver real-time updates to your applications:

1. Your application opens an SSE connection to the KMS Events API.
2. When a subscribed event occurs (e.g., a secret is updated), KMS pushes a notification through the connection.
3. Your application receives the event instantly and can take appropriate action.

<Note>
  Event Subscriptions are designed for real-time communication and do not include persistence or replay
  capabilities—events are delivered once and are not stored for future retrieval. Ensure your application
  maintains an active connection to receive events.
</Note>

## Supported Events

You can subscribe to the following event types:

### Secrets

| Event | Description |
|-------|-------------|
| `secret:create` | Triggered when a new secret is created |
| `secret:update` | Triggered when an existing secret is modified |
| `secret:delete` | Triggered when a secret is removed |
| `secret:import-mutation` | Triggered when a secret changes via an import |


## Permissions Setup

To receive events, the machine identity must have the **Secret Events** permission with the appropriate actions enabled.

<Steps>
  <Step title="Open Project Roles">
    ![Project Detail](/images/platform/events/project-detail.png)
    ![Project Access](/images/platform/events/project-access.png)

    Go to **Access Management** and select **Project Roles**.
  </Step>

  <Step title="Create or edit a role">
    ![Project Role](/images/platform/events/project-role.png)

    Create a new role for event subscriptions, or edit an existing one.
  </Step>

  <Step title="Add a policy to the role">
    ![Role Detail](/images/platform/events/role-detail.png)

    Select the resources the role should have access to.

    ![Add policy](/images/platform/events/add-policy.png)
  </Step>

  <Step title="Enable event actions">
    ![Policy setting](/images/platform/events/policy-setting.png)

    Enable the actions corresponding to the events you want to receive (e.g., read, create, update, delete).
  </Step>
</Steps>

### Filtering Events with Conditions

You can scope events to specific secret paths, environments, or other conditions.

![Policy condition](/images/platform/events/policy-condition.png)

This allows you to receive only the events relevant to your use case, reducing noise and improving efficiency.

## Getting Started

Event Subscriptions are currently available via the [Events API](/api-reference/endpoints/events). Support for SDKs, Kubernetes Operator, and other integrations is coming soon.

### Prerequisites

You need an authentication token from a machine identity. Follow the [machine identities documentation](/documentation/platform/identities/machine-identities#authentication-methods) to set up authentication.

### Subscribing to Events

To subscribe to events, make a request to the events endpoint with your project ID and optional filters.

![Postman Subscription](/images/platform/events/postman-subscribe.png)

#### Request Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `projectId` | string | The ID of the project to subscribe to |
| `register` | array | List of event filters |
| `register[].conditions` | object | Optional conditions to filter events |
| `register[].conditions.environmentSlug` | string | Filter by environment (e.g., `dev`, `staging`, `prod`) |
| `register[].conditions.secretPath` | string | Filter by secret path (e.g., `/api/keys`) |


The endpoint responds with `Content-Type: text/event-stream` to initiate an SSE connection. In the cURL example below, we use the `-N` flag to keep the connection open to receive incoming events from KMS.

```bash
curl -X POST -N --location \
  'https://kms.hanzo.ai/api/v1/events/subscribe/project-events' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer <identity-access-token>" \
  --data '{
    "projectId": "<project-id>",
    "register": [
      {
        "event": "secret:create",
        "conditions": {
          "environmentSlug": "dev",
          "secretPath": "/micro_service1"
        }
      },
      {
        "event": "secret:update",
        "conditions": {
          "environmentSlug": "staging",
          "secretPath": "/**"
        }
      },
      {
        "event": "secret:delete",
        "conditions": {
          "environmentSlug": "prod",
          "secretPath": "/database"
        }
      },
      {
        "event": "secret:import-mutation",
        "conditions": {
          "environmentSlug": "prod",
          "secretPath": "/database"
        }
      }
    ]
  }'
```

### Response Format

<AccordionGroup>
<Accordion title="Secret Changes">
  - Event triggered on a secret change

```json
{
    "projectType": "secret-manager",
    "data": {
        "eventType": "secret:create|update|delete",
        "payload": [
          {
            "environment": "staging",
            "secretPath": "/",
            "secretKey": "SECRET_KEY1"
          },
          {
            "environment": "staging",
            "secretPath": "/",
            "secretKey": "SECRET_KEY2"
          }
        ],
    }
}
```
</Accordion>
<Accordion title="Secret Import Mutation">
  - Event triggered on a secret change in an import 


```json
{
    "projectType": "secret-manager",
    "data": {
        "eventType": "secret:import-mutation",
        "payload": {
            "environment": "staging",
            "secretPath": "/"
        }
    }
}
```
</Accordion>
</AccordionGroup>

<Tip>
  For complete API specifications and additional examples, see the [API Reference](/api-reference/endpoints/events).
</Tip>