Event Subscriptions

Event Subscriptions is a paid feature that is available under the Enterprise license. Please contact sales@hanzo.ai.

Event Subscriptions allow you to receive real-time notifications when specific actions occur within your Hanzo 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) to deliver real-time updates to your applications:

Your application opens an SSE connection to the Hanzo KMS Events API.

When a subscribed event occurs (e.g., a secret is updated), Hanzo KMS pushes a notification through the connection.

Your application receives the event instantly and can take appropriate action.

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.

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.

Project Detail Project Access

Go to Access Management and select Project Roles.

Project Role

Create a new role for event subscriptions, or edit an existing one.

Role Detail

Select the resources the role should have access to.

Add policy

Policy setting

Enable the actions corresponding to the events you want to receive (e.g., read, create, update, delete).

Filtering Events with Conditions

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

Policy condition

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

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 Hanzo KMS.

curl -X POST -N --location \
  'https://app.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

Event triggered on a secret change

{
    "projectType": "secret-manager",
    "data": {
        "eventType": "secret:create|update|delete",
        "payload": [
          {
            "environment": "staging",
            "secretPath": "/",
            "secretKey": "SECRET_KEY1"
          },
          {
            "environment": "staging",
            "secretPath": "/",
            "secretKey": "SECRET_KEY2"
          }
        ],
    }
}

Event triggered on a secret change in an import

{
    "projectType": "secret-manager",
    "data": {
        "eventType": "secret:import-mutation",
        "payload": {
            "environment": "staging",
            "secretPath": "/"
        }
    }
}

For complete API specifications and additional examples, see the API Reference.

On this page