Event Subscriptions - Infisical

<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 Infisical 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 Infisical Events API.
When a subscribed event occurs (e.g., a secret is updated), Infisical pushes a notification through the connection.
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.

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.

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

bash

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