> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event subscriptions

> Subscribe to events in Infisical for real-time updates

> [!NOTE]
>
> Event Subscriptions is a paid feature that is available under the Enterprise license.
> Please contact [sales@infisical.com](mailto:sales@infisical.com).

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)](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 Infisical Events API.
2. When a subscribed event occurs (e.g., a secret is updated), Infisical 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 don't include persistence or replay
> capabilities—events are delivered once and aren't 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.

**1. Open Project Roles**

![Project Detail](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/project-detail.png)

![Project Access](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/project-access.png)

Go to **Access Management** and select **Project Roles**.

**2. Create or edit a role**

![Project Role](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/project-role.png)

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

**3. Add a policy to the role**

![Role Detail](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/role-detail.png)

Select the resources the role should have access to.

![Add policy](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/add-policy.png)

**4. Enable event actions**

![Policy setting](https://mintlify.s3.us-west-1.amazonaws.com/infisical/images/platform/events/policy-setting.png)

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](https://mintlify.s3.us-west-1.amazonaws.com/infisical/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](https://infisical.com/docs/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](https://infisical.com/docs/documentation/platform/identities/machine-identities.md#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](https://mintlify.s3.us-west-1.amazonaws.com/infisical/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 Infisical.

```bash theme={"dark"}
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

> [accordion] Secret Changes
>
> * Event triggered on a secret change
>
> ```json theme={"dark"}
> {
>     "projectType": "secret-manager",
>     "data": {
>         "eventType": "secret:create|update|delete",
>         "payload": [
>           {
>             "environment": "staging",
>             "secretPath": "/",
>             "secretKey": "SECRET_KEY1"
>           },
>           {
>             "environment": "staging",
>             "secretPath": "/",
>             "secretKey": "SECRET_KEY2"
>           }
>         ],
>     }
> }
> ```

> [accordion] Secret Import Mutation
>
> * Event triggered on a secret change in an import
>
> ```json theme={"dark"}
> {
>     "projectType": "secret-manager",
>     "data": {
>         "eventType": "secret:import-mutation",
>         "payload": {
>             "environment": "staging",
>             "secretPath": "/"
>         }
>     }
> }
> ```

> [!TIP]
>
> For complete API specifications and additional examples, see the [API Reference](https://infisical.com/docs/api-reference/endpoints/events).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.