Notifications for Confluent Cloud

You can manage notifications for account, billing and service events with the Confluent Cloud Console or with a REST API. Additionally you can configure how you are notified for some of the notification types.

For Required and Recommended notification types, notifications are sent by email to users directly assigned the OrganizationAdmin role. Users granted the OrganizationAdmin role through group mappings are not sent notifications. All other RBAC roles have read-only access to notifications.

For notifications, you should understand the following terms:

Notification type: The type of notification based on the Confluent Cloud event that has occurred. Each notification type defines a condition that must be met, and they are categorized by Account, Billing and Licensing, and Service, and they can be filtered by by severity level. For example, a Dedicated cluster shrink failure is a warning-level service notification type.
Integration: Describes the configured notification channel for sending a notification event: Email, Microsoft Teams, Slack or a generic Webhook. The default integration is email, and notifications are sent to the organization’s admin or if using RBAC, users that have the OrganizationAdmin role.
Subscription: Represents the association of a notification type to an integration channel. A user creates subscriptions for a particular notification type and as a result is notified through the integration channels they have configured for that subscription.

You can view the current notification subscriptions and configure additional integrations and subscriptions to those integrations using the Confluent Cloud Console or a REST API. For example, you can configure a Slack integration, and then subscribe to this integration for a Kafka cluster shrink failure notification type.

See a list of subscriptions

You can view the your notification integrations and subscriptions in the Cloud Console or by making a GET call to the REST API.

Cloud Console

To see a list of notification subscriptions and integrations you have currently configured access the Manage notifications page by clicking the Alert bell icon in the upper right of the console.

Subscriptions can filtered by:

Category
Severity level
Integration
Whether the subscription is Enabled or not

REST API

To list all of the subscriptions associated with that subscription, make a GET call to the subscriptions endpoint. The request should include an authentication header that contains an API key and secret scoped for resource management, Base64 encoded. For more about authentication, see Authentication. This will retrieve a filtered and paginated list of all subscriptions along with integrations details associated with them. For a full list of APIs, see Confluent Cloud APIs.

GET /notifications/v1/subscriptions HTTP/1.1
Host: api.confluent/cloud

A successful response will be 200 OK with a JSON payload that contains a subscription list for that organization. The example response that follows has been been shortened for brevity.

HTTP 200 OK
{
   "api_version": "notifications/v1",
   "kind": "SubscriptionList",
   "metadata": {
      "first": "https://api.confluent.cloud/notifications/v1/subscriptions"
   },
   "data": [
      {
            "notification_type": {
               "resource_name": "crn://confluent.cloud/notification-type=nt-12JlG",
               "api_version": "notifications/v1",
               "id": "nt-l2JlG",
               "kind": "notification-type",
               "related": "https://api.confluent.cloud/notifications/v1/notification-types/nt-12JlG"
            },
            "integrations": [
               {
                  "resource_name": "crn://confluent.cloud/integration=i-e0KAB",
                  "api_version": "notifications/v1",
                  "id": "i-e0KAB",
                  "kind": "integration",
                  "related": "https://api.confluent.cloud/notifications/v1/integrations/i-e0KAB"
               }
            ],
            "current_state": "ENABLED",
            "api_version": "notifications/v1",
            "kind": "Subscription",
            "id": "s-56R4y",
            "metadata": {
               "self": "https://api.confluent.cloud/notifications/v1/subscriptions/s-56R4y",
               "resource_name": "crn://confluent.cloud/subscription=s-56R4y",
               "created_at": "2022-08-23T23:02:18.455Z",
               "updated_at": "2022-08-23T23:02:18.455Z"
            }
      },
      {
            "notification_type": {
               "resource_name": "crn://confluent.cloud/notification-type=nt-DbPQ9",
               "api_version": "notifications/v1",
               "id": "nt-DbPQ9",
               "kind": "notification-type",
               "related": "https://api.confluent.cloud/notifications/v1/notification-types/nt-DbPQ9"
            },
            "integrations": [
               {
                  "resource_name": "crn://confluent.cloud/integration=i-e0KAB",
                  "api_version": "notifications/v1",
                  "id": "i-e0KAB",
                  "kind": "integration",
                  "related": "https://api.confluent.cloud/notifications/v1/integrations/i-e0KAB"
               },
            {
            "resource_name": "crn://confluent.cloud/integration=i-jYa83",
            "api_version": "notifications/v1",
            "id": "i-jYa83",
            "kind": "integration",
            "related": "https://api.confluent.cloud/notifications/v1/integrations/i-jYa83"
         }
            ],
            "current_state": "ENABLED",
            "api_version": "notifications/v1",
            "kind": "Subscription",
            "id": "s-rZ9yx",
            "metadata": {
               "self": "https://api.confluent.cloud/notifications/v1/subscriptions/s-rZ9yx",
               "resource_name": "crn://confluent.cloud/subscription=s-rZ9yx",
               "created_at": "2022-08-23T23:03:19.328Z",
               "updated_at": "2022-09-15T23:49:00.422Z"
            }
      }
   ]
}

Configure integrations and subscriptions

You can configure Slack, Microsoft Teams or generic webhook integrations for some notification types if you are an organization administrator, or if using RBAC, you have OrganizationAdmin access to the Confluent Cloud account.

Microsoft Teams transitions to new URL structure for webhooks

Microsoft Teams is transitioning to a new URL structure for webhooks. You must update webhooks for your existing integrations and create new-style webhooks for future integrations. For more information, see Retirement of Office 365 connectors within Microsoft Teams. To learn how to update existing webhooks, use the steps in the previous link or see, Update connectors URL from the Microsoft Teams documentation.

To configure an integration and subscribe to a notification type for that integration:

Cloud Console

Sign in to Confluent Cloud, and click the Alert bell icon to display the Manage notifications page.
Hover on a notification type, and click the edit icon.
Important
Some notifications are not configurable. In these cases, the edit icon does not appear.
Check to enable or uncheck to disable the subscriptions. You can also configure a new integration.
- Email - Enter one or more roles or users to receive notification emails. Email will be checked by default for Recommended and Required notification types, and the OrganizationAdmin role configured by default to receive emails.
- Webhook - To add a new integration, click Add a webhook URL and enter a Name for the integration and the Webhook URL.
The webhook will receive messages in the following format:
```
{
   id: string [required]
   title: string
   message: string
   created_at: string
}
```
- Slack - To add a new integration, click add a slack URL and enter a Name for the integration, such as the channel or team name that will receive the notification, and the Slack URL.
- Microsoft Teams - To add a new integration, click add a Microsoft Teams URL and enter a Name for the integration, such as the channel or team name that will receive the notification, and the Microsoft Teams URL.
Click Verify for each URL you enter, and Confluent Cloud will send a test message to the URL. Once a URL is verified, you can click Save to save the integration, and check it to add a subscription using that integration.
If the URL cannot be verified, you cannot save your changes.
Once you have selected integrations and successfully added and selected a URL for each integration, under Test and Finish. Click Update to save your changes.

REST API

To configure a subscription with the REST API, you first create an an integration, then retrieve a list of notification types, and specify an integration and notification type to add a subscription. For a full list of APIs, see Confluent Cloud APIs.

To create the integration, send a POST request to the integrations endpoint, and include the description of the integration as a JSON payload. The request should include an authentication header that contains an API key and secret scoped for resource management, Base64 encoded. For more about authentication, see Authentication.

The payload should include the name, description and URL for a Slack, Microsoft Teams, or generic webhook integration.

POST /notifications/v1/integrations HTTP/1.1
Host: api.confluent/cloud
{
"display_name": "Slack integration",
"description": "A Slack channel integration",
"target": {
  "kind": "Slack",
  "webhook_url": "https://hooks.slack.com/services/T03QJN0HR12/B123QDZTG3W/abczdb"
 }
}

A successful response will be a 201 Created message with a JSON payload that resembles the following:

HTTP 1.1 201 CREATED
{
   "api_version": "notifications/v1",
   "kind": "Integration",
   "id": "i-a1KrA",
   "metadata": {
      "self": "https://api.confluent.cloud/notifications/v1/integrations/i-a1KrA",
      "resource_name": "crn://confluent.cloud/integration=i-e0KrA",
      "created_at": "2022-09-15T23:52:20.884Z",
      "updated_at": "2022-09-15T23:52:20.884Z"
   },
   "display_name": "Slack integration",
   "description": "A Slack channel integration",
   "target": {
      "kind": "Slack",
      "webhook_url": "https://hooks.slack.com/services/T03QJN0HR12/B123QDZTG3W/abczdb"
   }
}

Next, make a GET call to the notfication-types endpoint to retrieve a list of notifications you can subscribe to. The request should include an authentication header that contains an API key and secret scoped for resource management, Base64 encoded. For more about authentication, see Authentication. For a full list of APIs, see Confluent Cloud APIs.

GET /notifications/v1/notification-types HTTP/1.1
Host: api.confluent/cloud

A successful response will look like the following (returned list shortened for brevity):

HTTP 1.1 200 OK
{
"api_version": "notifications/v1",
"kind": "NotificationTypeList",
"metadata": {
   "first": "https://api.confluent.cloud/notifications/v1/notification-types"
},
"data": [
   {
         "api_version": "notifications/v1",
         "kind": "NotificationType",
         "id": "nt-DbPQ9",
         "metadata": {
            "self": "https://api.confluent.cloud/notifications/v1/notification-types/nt-DbPQ9",
            "resource_name": "crn://confluent.cloud/notification-type=nt-DbPQ9",
            "created_at": "2022-04-11T13:56:58.817769Z",
            "updated_at": "2022-04-11T13:56:58.817769Z"
         },
         "display_name": "30 days have elapsed since org was created",
         "description": "30 days have elapsed since org was created",
         "category": "BILLING_LICENSING",
         "subscription_priority": "RECOMMENDED",
         "is_included_in_plan": true,
         "severity": "INFO"
   },
   {
         "api_version": "notifications/v1",
         "kind": "NotificationType",
         "id": "nt-abc123",
         "metadata": {
            "self": "https://api.confluent.cloud/notifications/v1/notification-types/nt-abc123",
            "resource_name": "crn://confluent.cloud/notification-type=nt-abc123",
            "created_at": "2022-04-21T12:15:44.503490Z",
            "updated_at": "2022-04-21T12:15:44.503490Z"
         },
         "display_name": "Reached 50% of your environment quota",
         "description": "Confluent Cloud Service Quota usage > 50%.",
         "category": "SERVICE",
         "subscription_priority": "OPTIONAL",
         "is_included_in_plan": true,
         "severity": "INFO"
   }
   ]
}

Next you create a subscription by sending a POST request to the subscriptions endpoint with a JSON payload that denotes the current state of the subscription, identifies the notification type you want to subscribe to, the integration ID for the integration you want to configure, and the environment where it was created. You can only create one subscription per notification type. Omitting current_state or attempts to create more than one subscription result in an error. The request should include an authentication header that contains an API key and secret scoped for resource management, Base64 encoded. For more about authentication, see Authentication. For a full list of APIs, see Confluent Cloud APIs.

POST /notifications/v1/subscriptions HTTP/1.1
{
   "current_state": "ENABLED",
   "notification_type": {
      "resource_name": "crn://confluent.cloud/notification-type=nt-abc123",
      "api_version": "notifications/v1",
      "id": "nt-abc123",
      "kind": "notification-type",
      "related": "https://api.confluent.cloud/notifications/v1/notification-types/nt-abc123"
    },
   "integrations": [
      {
         "id": "i-e0KrA",
         "environment": "env-0xovp6"
      }
   ]
}

A successful response will resemble the following:

 201 ACCEPTED
 {
 "notification_type": {
    "resource_name": "crn://confluent.cloud/notification-type=nt-abc123",
    "api_version": "notifications/v1",
    "id": "nt-abc123",
    "kind": "notification-type",
    "related": "https://api.confluent.cloud/notifications/v1/notification-types/nt-abc123"
 },
 "integrations": [
    {
          "resource_name": "crn://confluent.cloud/integration=i-e0KrA",
          "api_version": "notifications/v1",
          "id": "i-e0KrA",
          "kind": "integration",
          "related": "https://api.confluent.cloud/notifications/v1/integrations/i-e0KrA"
    }
 ],
 "current_state": "ENABLED",
 "api_version": "notifications/v1",
 "kind": "Subscription",
 "id": "s-3GRE9",
 "metadata": {
    "self": "https://api.confluent.cloud/notifications/v1/subscriptions/s-3GRE9",
    "resource_name": "crn://confluent.cloud/subscription=s-3GRE9",
    "created_at": "2022-09-21T18:14:20.952Z",
    "updated_at": "2022-09-21T18:14:20.952Z"
 }
}

Connector notifications

The Confluent Cloud Console allows you to enable/disable notifications for connectors using the connector notification service feature.

If you enable this feature, Confluent Cloud sends a notification to your desired notification channel(s)–email, Slack, Microsoft Teams, or Generic Webhook–when the connector transitions from/to either one of the following states:

Provisioning to Running
Provisioning to Failed
Running to Degraded
Running to Failed

Each notification message includes the following content:

Status of the connector (Running, Failed, or Degraded)
Connector name
Connector ID
Cluster ID

You can troubleshoot any issue further by clicking View connector from the message content as shown in the following example:

../_images/ccloud-connector-failed-email.png

State transitions and notification types

The following sections describe connector state transitions and their notification types.

Provisioning to Running

When you first launch a connector, it enters into the PROVISIONING state. If the connector launches successfully, the connector state changes to RUNNING. Once this occurs, Confluent Cloud sends you a notification about the new connector to the selected notification channel(s) denoting the connector is up and running.

Provisioning to Failed

The connector can transition from PROVISIONING to RUNNING state for several reasons, including:

A system error
The connector failed to start due to an error
API keys resource-scoped for Kafka clusters are not propagated to Data Plane
Schema Registry role bindings are not propagated to Data Plane

If any of these situations occur, Confluent Cloud sends a notification message to your desired notification channel(s) denoting the connector failed.

Running to Failed

If all connector tasks fail, the connector enters into the FAILED state. A running connector can go into FAILED state for a number of reasons, including:

Configuration validation errors
Network connectivity issues

In any of these situations occur, Confluent Cloud sends a notification message to your desired notification channel(s) denoting the connector failed.

Running to Degraded

If some tasks go unassigned while the connector is running, the connector goes from RUNNING state to DEGRADED. In this case, Confluent Cloud sends a notification message to your desired notification channel(s) denoting the connector degraded.

Notification severity levels

The following table describes the severity levels for notifications.

State	Summary	Description
Critical	Highly recommended actions	High impact notifications which need immediate attention. Address these notifications with priority.
Warn	Potential future issues	Warning notifications you can address now or later.
Info	Informational events	Informational notifications about the normal operation of your cluster.

Required notifications

The following table describes required notifications.

Severity level	Category	Description
Critical	Account	Organization has been suspended (end of free trial).
Critical	Service	Access to a customer-managed encryption key (BYOK) has been disrupted.
Warn	Billing and licensing	Free usage is 80% consumed or free usage expires in 3 days.
Warn	Security	SAML certificate is expiring soon.
Warn	Security	OrganizationAdmin Role Binding Granted.
Warn	Security	OrganizationAdmin Email Changed.

Optional notifications

The following table describes optional notifications.

Severity level	Category	Description
Info	Billing and licensing	30 days have elapsed since org was created.
Info	Billing and licensing	50% or more of free trial usage consumed.
Critical	Service	Kafka cluster expansion failure.
Critical	Service	Cloud Service Quota reached 100% usage.
Critical	Service	Connector in FAILED state.
Critical	Service	Flink statement failure.
Warn	Service	Kafka cluster shrink failure.
Warn	Service	Cloud Service Quota surpassed 90% usage.
Warn	Service	Flink statement degraded
Warn	Service	Flink statement auto-stopped.
Info	Service	Kafka cluster expansion complete.
Info	Service	Kafka cluster shrink complete.
Info	Service	Cloud Service Quota surpassed 50% usage.
Info	Service	Connector state transition from PROVISIONING to RUNNING.