Notification destinations

Notification destinations define where CloudQuery Platform sends notifications when alerts are triggered, policy violations are detected, or an insight matches a notification rule. There are three destination types: Slack (native integration with OAuth and channel selection), Microsoft Teams (incoming webhook URL), and Webhook (HTTP POST to any endpoint).

A destination is connected once and reused. Notification rules decide which insights reach it and what each message says, so you do not need a separate destination per message.

Create a notification destination

1. In the sidebar, click your user icon and select Organization settings.
2. Open the Notification destinations section.
3. Click Add notification destination.
4. Enter a Destination name to identify this destination when configuring alerts (e.g., “Slack - Security Channel” or “PagerDuty Webhook”).
5. Select a Destination type: Slack, Microsoft Teams, or Webhook.

The fields that follow depend on the type you select.

Slack destinations

The Slack destination type connects to your Slack workspace via OAuth and sends notifications directly to selected channels. No webhook URL or custom payload is required.

Configuration

1. Select Slack from the Destination type dropdown.
2. Click Connect workspace to start the OAuth flow. A new window opens where you authorize CloudQuery to post to your Slack workspace.
3. After authorization, select one or more channels from the Slack channels dropdown.
4. Optionally, enter a Custom message to prepend to the alert notification.
5. Click Save notification destination.

How Slack notifications work

When an alert triggers, CloudQuery posts a message to each selected channel. The message includes the alert details (query name, status, severity, violations). If you set a custom message, it appears above the alert details.

Microsoft Teams destinations

Microsoft Teams destinations post to a channel through an incoming webhook URL.

Configuration

1. Select Microsoft Teams from the Destination type dropdown.
2. Set the Microsoft Teams Webhook URL. Create one in Teams with a workflow or an incoming webhook connector.
3. Optionally, enter a Custom message to prepend to the notification.
4. Click Save notification destination.

The URL is stored encrypted and is not shown again after saving. To change it, enter a new one.

Webhook destinations

Webhook destinations send an HTTP POST request to any URL you specify. Use this type for services like PagerDuty, Opsgenie, or custom HTTP endpoints.

Configuration

1. Select Webhook from the Destination type dropdown.
2. Set the Destination URL: the HTTP(S) endpoint to receive notifications.
3. Configure the Web request body: the default JSON payload sent with each notification. Alerts send this body directly, with its placeholder variables filled in — an insight-driven notification rule ignores it and sends its own message content instead, defaulting to the canonical cq.notification.v1 payload if you never edit it.
4. Add HTTP Headers: set Content-Type: application/json for most destinations.
5. Under Webhook signing, set a Signing secret of at least 16 characters. CloudQuery signs every delivery to this destination with an X-CloudQuery-Signature header. See Webhook receivers for how to verify it.
6. Click Save notification destination.

The signing secret is stored encrypted and never returned. Leave the field blank when editing to keep the existing secret, or enter a new one to replace it.

Example: Slack incoming webhook

If you prefer to use a Slack Incoming Webhook instead of the native Slack integration, select Webhook as the destination type, set the webhook URL, add the Content-Type: application/json header, and use this request body with the alert placeholder variables:

{
  "text": "*{{alert_status}}*: {{query_name}}\nSeverity: {{alert_severity}}\nViolations: {{alert_violations}}\n<{{query_url}}|View in CloudQuery>"
}

Example: generic webhook

For services like PagerDuty, Opsgenie, or custom HTTP endpoints:

{
  "title": "CloudQuery Alert: {{query_name}}",
  "status": "{{alert_status}}",
  "severity": "{{alert_severity}}",
  "message": "{{alert_message}}",
  "violations": "{{alert_violations}}",
  "url": "{{query_url}}"
}

Test a destination

After saving, click Send test notification to verify the endpoint is reachable and the payload format is correct. Webhook destinations receive the web request body with placeholders filled from sample values, signed with the stored signing secret. Slack and Microsoft Teams destinations receive a test message.

Manage destinations

Notification destinations are shared across every alert and notification rule. You can:

• Edit a destination’s configuration at any time
• Delete a destination (alerts and rules using it stop sending to that endpoint)
• Reference the same destination from any number of rules, each with its own message content

Note: The destination type cannot be changed after creation. To switch types, create a new destination.

Troubleshooting

Notifications are not being received

• Verify the destination URL is reachable from the CloudQuery Platform server (webhook destinations only).
• Check that the Content-Type header matches what the receiving service expects (usually application/json).
• Use the Send test notification button to confirm the endpoint responds.
• Alerts only send notifications on state changes. See Alerts: How Alerts Work for details.

Slack connection failed

• Verify that the Slack integration is configured for your CloudQuery Platform instance. If you see “Slack integration is not configured,” contact your administrator.
• Make sure you authorized CloudQuery in the correct Slack workspace.
• If channels are not appearing in the dropdown, confirm the workspace connection completed and refresh the page.

Destination cannot parse the request body

Ensure the Content-Type header is set correctly. Most webhook endpoints expect application/json, but some services require application/x-www-form-urlencoded or other content types.

Related features

• Policies: configure notifications for policy violations
• Alerts: trigger notifications when SQL queries return results

Programmatic access

Notification destinations can be managed via the Platform API. See the Platform API Reference (alerts section) for endpoint details.

Next steps

• Notification rules — route insights by account, tag, app, environment, or owner
• Alerts — create SQL-based alerts that send notifications
• Policies — monitor compliance and trigger notifications on violations
• Reports — schedule reports with notifications