Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Configure an Alert Integration

  • Capella Operational
      +
      If your organization uses a third-party tool to receive, assign, and monitor service issues, you can configure an alert integration to send notifications from Capella to that third-party tool automatically. You can then use workflows defined in the third-party tool to route information about metric-derived critical- and warning-level events when they occur in Capella.
      Capella offers alert integration for clusters and App Services on the paid Enterprise or Developer Pro subscription plans only. Capella does not support alert integration 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 the destination URL for the webhook and 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:

      1. In your third-party tool of choice, set up the incoming webhook. You’ll need the URL and the authentication details.

      2. 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.
      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"
}

      Prerequisites

      For full access to Capella alert integrations, you must have one of the following roles:

      • Organization Owner

      • Project Creator

      • Project Owner

      • Project Manager

      See Organization roles and Project roles.

      In addition, users with the following roles have read-only access to Capella alert integrations:

      When you add an alert integration, you must supply:

      • An identifying name.

      • The URL that uniquely identifies the destination for the alert integration’s notifications.

      • An authentication and authorization method and credentials:

        • Basic auth requires a username and password.

        • Bearer token auth requires an access token.

      You use the third-party tool to obtain the URL and credentials.

      Adding an Alert Integration

      To use the Capella Management API to create and configure an alert integration, see Create Alert Integration.

      You can add one alert integration for each project.

      To add an alert integration using the Capella UI:

      1. Select a project from the project list.

      2. Select the Alerts tab.

      3. Select Add integrations.

      4. Enter an identifying Display Name. The value can include the alphanumeric characters A-Z, a-z, and 0-9, spaces, and the hyphen - and underscore _ special characters only.

      5. Enter the destination Webhook URL for the notifications sent by this alert integration. Capella requires a secure connection, so the URL must begin with https://. You obtain this URL from the third-party tool.

      6. Specify an Authentication method:

        • Basic: supply the username and password established with the third-party tool.

        • Bearer Token: supply the access token generated by the third-party tool.

      7. To add HTTP headers or filtering, click Show Advanced Settings.

        1. To add an HTTP header, select Add Custom HTTP Header and then enter a Key and a Value.

          Key names can include the alphanumeric characters A-Z, a-z, and 0-9, and the hyphen - and underscore _ special characters only.

          Values can include all of the characters that a key name can contain plus the following special characters: : ; . , \ / " ' ? ! ( ) { } [ ] @ < > = + * # $ & ` | ~ ^ %.

        2. To prevent the alert integration from sending messages for certain clusters or App Services, use the drop-down lists to choose entities to exclude.

      8. Click Test Connection. You cannot save the alert integration until the URL destination and auth credentials are accurately configured and the connection test succeeds.

      9. Click Add Integration. Capella adds and enables the alert integration.

      Editing an Alert Integration

      To use the Capella Management API to edit an alert integration, see Update Alert Integration.

      To edit an alert integration using the Capella UI:

      1. Select a project from the project list.

      2. Select the Alerts tab.

      3. Click the Name of the alert integration you want to edit.

      See the steps for adding an alert integration for information about the settings you can configure.

      Deleting an Alert Integration

      To use the Capella Management API to delete an alert integration, see Delete Alert Integration.

      To delete an alert integration using the Capella UI:

      1. Select a project from the project list.

      2. Select the Alerts tab.

      3. Locate the alert integration you want to delete.

      4. Use the Trash icon at the end of the row to delete the alert integration.

      Troubleshooting

      • Message Queuing and Delivery

        Capella applies a first in/first out queue to send one alert notification at a time. Typically, Capella sends alert notifications within milliseconds of creation. After Capella sends a notification, the third-party tool controls queuing and the timing of delivery via the incoming webhook.

      See Also