Skip to main content

Receiver Groups

Receiver groups define where your alerts should be sent (Slack, Email, PagerDuty, etc.).

Authentication​

These APIs can be accessed programmatically using the Admin Port 3199.

Headers Required:

  • (Optional) Authorization: Bearer <ADMIN_TOKEN>
  • Content-Type: application/json
info

When http-token-admin is enabled in CubeAPM's config.properties, requests must include the corresponding token in the Authorization header when using curl to CREATE, UPDATE, or DELETE receiver groups.

Create Receiver Group​

When creating a receiver group, one or multiple receivers of the same or different types can be mapped to a single receiver group.

Endpoint: POST http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups

Request Parameters​

ParameterTypeDescription
namestringA descriptive name for the notification group.
receiver.slack_configsarrayContains Slack configurations. Requires channel (e.g., "#alerts").
receiver.email_configsarrayContains email configurations. Requires to (e.g., "team@company.com").
receiver.pagerduty_configsarrayRequires service_name and routing_key.
receiver.webhook_configsarrayRequires url to send a POST request. Optionally accepts custom headers (key-value pairs) and a custom body string.
receiver.msteamsv2_configsarrayRequires webhook_url for Microsoft Teams incoming webhook integration.
receiver.jira_configsarrayRequires project and issue_type to automatically create Jira tickets.
receiver.opsgenie_configsarrayRequires api_key for OpsGenie routing.
receiver.googlechat_configsarrayRequires url for Google Chat webhooks.
info

Since CubeAPM uses the standard Alertmanager schema, you can refer to the official Prometheus Alertmanager Documentation for detailed descriptions and additional integration fields (like send_resolved, text, title, etc.) for MS Teams, Jira, Slack, PagerDuty, and more!

Common Integration Parameters​

In addition to standard Alertmanager fields, CubeAPM supports specific parameters inside your receiver configurations (e.g., inside a slack_configs object):

ParameterTypeDescription
send_resolvedbooleanWhether or not to notify when the alert is resolved (e.g. returns to a healthy state). Default is true.
cube_show_querybooleanIf true, includes the raw PromQL/Metrics query that triggered the alert inside the notification payload. Default is false.
cube_show_sample_logbooleanIf true, includes a sample log line from the evaluation (if applicable for Log-based alerts). Default is false.

Curl Example​

curl -X POST "http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Slack Alerts",
           "receiver": {
             "slack_configs": [
               { 
                 "channel": "production-alerts", 
                 "send_resolved":true,
                 "cube_show_query":false,
                 "cube_show_sample_log":false
               }
             ]
           }
        }'

Response Format​

The response is a JSON object with the following structure:

FieldTypeDescription
idintegerUnique identifier for the receiver group.
namestringThe name of the notification group.
receiverobjectThe saved configuration for the integrations (e.g., slack_configs, email_configs).

For example:

{
  "id": 3,
  "name": "Slack Alerts",
  "receiver": {
    "slack_configs": [
      {
        "channel": "production-alerts"
      }
    ]
  }
}

Fetch All Receiver Groups​

Endpoint: GET http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups

Curl Example​

Fetch all receiver groups:

curl -X GET "http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups"

Response Format​

The response format is a JSON array of receiver group objects. See Create Receiver Group Response Format for the schema structure.

For example:

[
  {
    "id": 3,
    "name": "Slack Alerts",
    "receiver": {
      "slack_configs": [
        {
          "channel": "production-alerts"
        }
      ]
    }
  }
]

Fetch Specific Receiver Group​

Endpoint: GET http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups

Curl Example​

Fetch a specific receiver group by ID:

curl -X GET "http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups?id=1"

Response Format​

The response is a JSON object representing the specific receiver group. See Create Receiver Group Response Format for the schema structure.

For example:

{
  "id": 3,
  "name": "Slack Alerts",
  "receiver": {
    "slack_configs": [
      {
        "channel": "production-alerts"
      }
    ]
  }
}

Update / Delete Receiver Groups​

warning

The PUT request replaces the entire Receiver Group configuration. You must include all existing configurations (such as the receiver integrations) in your payload; otherwise, they will be overwritten and removed!

Update a Receiver Group (PUT)​

Endpoint: PUT http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups

curl -X PUT "http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups" \
     -H "Content-Type: application/json" \
     -d '{
           "id": 1,
           "name": "Updated Name",
           "receiver": {
             "slack_configs": [
               { "channel": "production-alerts-v2" }
             ]
           }
         }'

Delete a Receiver Group (DELETE)​

Endpoint: DELETE http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups?id=1

curl -X DELETE "http://<cubeapm-admin-host>:3199/api/alerts/api/v1/receivergroups?id=1"