Alert Integrations

Capella Operational

concept

An alert integration lets Capella send metric‑based notifications to a third‑party tool using a webhook.

Capella only offers alert integrations for clusters and App Services on the paid Enterprise or the Developer Pro Support Plans. Alert integrations are not available for the Basic plan.

About Alert Integrations

A webhook is a user-defined HTTP callback mechanism. The webhook allows an application—in this case Capella—to send an HTTP request with a JSON alert payload to a previously configured URL. On the receiving end, you can customize the third-party tool to direct alert messages from Capella into appropriate workflows and recipients.

The Capella alert integration feature is generic. You can configure alert integrations for any third-party tool that supports an incoming webhook. An alert integration requires a publicly accessible destination URL for the webhook, along with either basic or bearer token authentication and authorization.

Couchbase has verified the use of ServiceNow with the Capella alert integration feature. Refer to How to Integrate Webhooks into ServiceNow on the ServiceNow website for more information.

To send alert notifications from Capella to this and other third-party tools automatically:

In your third-party tool of choice, set up the incoming webhook. You’ll need the URL and the authentication details.
In Capella, add an alert integration to the project.

You can also view alert notifications in the Capella UI and receive them by email. See Receive Alerts.

Key Features

UI and API

Capella offers both a UI and a Capella Management API for working with alert integrations.

Project-level Definition

Rather than define alert integrations repetitively for every cluster, you configure alert integrations at the project level.

Metric-based Alerts

Alert integrations send metric-based alerts. The alert integration feature does not send alerts generated by operational failures. For a complete list of Capella alerts, see the Alert Reference.

Filtering

You can limit the notifications that an alert integration sends for the project. You can exclude specific clusters or App Services.

By default, an alert integration sends notifications for all of a project’s clusters and App Services that are on the paid Enterprise or Developer Pro plan. For clusters or App Services that are on the paid Basic plan, alerts are delivered only in the UI or by email.

Authentication and Authorization Options

You can use either basic or bearer token auth for messages posted by an alert integration.

JSON Payload

The notification messages that an alert integration sends include a JSON payload. The payload provides a structured framework for the message content, organizing its information into a set of easy-to-read JSON objects and key-value pairs.

HTTP Headers

You can define up to 20 HTTP headers to include with notification messages. HTTP headers provide additional flexibility for defining what occurs when the third-party tool receives a Capella alert notification. For example, a header can include information that further authenticates the notification, or that triggers a particular action or event.

Testing

Before you save an alert integration, you test the connection to the third-party tool to verify that its configuration is accurate.

Audit Trail

The activity log records all add, edit, and delete events for alert integrations. In addition, the activity log records any connection failure events that occur for an alert integration.

JSON Payload

The alert notification messages posted to a third-party tool by an alert integration include a JSON payload. The JSON payload provides a reliable, structured framework for message content.

When you configure workflow options for the incoming webhook, you can refer to the JSON payload to identify different actionable values. For example, the third-party tool might support the ability to route messages from Capella differently based on the project ID, severity, or resource identified in the JSON payload.

The payload of each message consists of the following JSON objects and keys:

Object or Key	Key	Description
details	kind	An abbreviated name for the alert.
	name	The display name of the alert.
	severity	Identifies the alert as either "critical" or "warning".
	summary	A brief description of the alert.
	description	A detailed description with potential causes and solutions. For more detailed information, see the Alert Reference.
tenant	id	The unique identifier of the project’s tenant.
	name	The user-defined name of the tenant.
project	id	The unique identifier of the project that contains the affected cluster or App Service.
	name	The user-defined name of the project.
resource	kind	Identifies the affected entity as "cluster" for a cluster or "appService" for an App Service.
	id	The unique identifier of the affected cluster or App Service.
	name	The user-defined name of the resource.
createdAt		When the event occurred: date and time in ISO 8601 format.

Object or Key

Key

Description

details

kind

An abbreviated name for the alert.

name

The display name of the alert.

severity

Identifies the alert as either "critical" or "warning".

summary

A brief description of the alert.

description

A detailed description with potential causes and solutions. For more detailed information, see the Alert Reference.

tenant

The unique identifier of the project’s tenant.

name

The user-defined name of the tenant.

project

The unique identifier of the project that contains the affected cluster or App Service.

name

The user-defined name of the project.

resource

kind

Identifies the affected entity as "cluster" for a cluster or "appService" for an App Service.

The unique identifier of the affected cluster or App Service.

name

The user-defined name of the resource.

createdAt

When the event occurred: date and time in ISO 8601 format.

Example: Low Node Disk Storage

{
    "details": {
        "kind": "disk_usage_high",
        "name": "Low Node Disk Storage",
        "severity": "warning",
        "summary": "A node has low disk storage.",
        "description": "A cluster node has low disk storage. The addition of more documents could fill the cluster and result in a service interruption. This issue could be due to spikes in data usage or natural data growth. Consider expanding the storage to resolve the issue."
    },
    "tenant": {
        "id": "b2e38a87-25a2-472a-ab10-e5f43862773d",
        "name": "Organization ABC"
    },
    "project": {
        "id": "13cfa96f-ade3-442e-ac37-eaa6ace76143",
        "name": "Mega App OLTP"
    },
    "resource": {
        "kind": "cluster",
        "id": "b5d3f347-3bad-4c6a-ad12-cf2b1f06647b",
        "name": "concavekonradzuse"

    },
    "createdAt": "2024-02-29T11:22:38.036547755Z"
}

Example: App Service High Access Errors Warning

{
    "details": {
        "kind": "syncgateway_import_errors_high_warning",
        "name": "App Service High Access Errors Warning",
        "severity": "warning",
        "summary": "In the last 5 minutes, more than 50 requests made to the App Endpoint failed to successfully authenticate.",
        "description": "In the last 5 minutes, more than 50 requests made to the App Endpoint failed to successfully authenticate. A high volume of unsuccessful authentications may indicate malicious clients attempting to access the system."
    },
    "tenant": {
        "id": "b5d3f347-472a-ade3-ad12-cf2b1f06647b",
        "name": "Acme Company"
    },
    "project": {
        "id": "b2e38a87-25a2-3bad-ab10-e5f43862773d",
        "name": "Wiley Genius"
    },
    "resource": {
        "kind": "appService",
        "id": "13cfa96f-4c6a-442e-ac37-eaa6ace76143",
        "name": "Platinum"
    },
    "createdAt": "2024-02-29T08:12:47.150356547Z"
}

Next Steps

Configure your alert integration to send Capella metric-based notifications to a third-party tool. To get started with:

The Capella UI, see Configure an Alert Integration.
The Management REST API, see Capella Management API.

For more information about monitoring your operational clusters, see