> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Circonus alert integration

> Send alert and recovery notifications from Circonus rulesets to Flashduty On-call through a contact group webhook.

Use the webhook contact method of a Circonus contact group to send alerts raised by rulesets to Flashduty On-call. Each Circonus alert (`alert_id`) maps to one Flashduty alert. When Circonus clears the alert, its recovery notification closes the Flashduty alert.

<div className="hide">
  ## In Flashduty On-call

  ***

  You can obtain an integration push URL in either of the following ways.

  ### Use a dedicated integration

  1. In the Flashduty console, select **Channel** and open a channel
  2. Select **Configuration** → **Integrations** → **Private integration**, then click **Add an integration**
  3. Select **Circonus**, then click **Save**
  4. Open the generated integration card and copy the **Push URL**

  ### Use a shared integration

  1. In the Flashduty console, select **Integration Center → Alert Events**
  2. Select **Circonus** and enter an integration name
  3. Configure the default route and select a channel; after creation, add more rules under **Route** if needed
  4. Click **Save** and copy the generated **Push URL**
</div>

## Configure Circonus

***

<Steps>
  <Step title="Add a webhook to a contact group">
    1. In Circonus, go to **Alerts → Contacts** and open (or create) the contact group that should receive the alerts
    2. Add a webhook (HTTP POST) contact method
    3. Paste the Flashduty push URL as the URL and append `&format=json`, for example:

    ```text theme={null}
    https://api.flashcat.cloud/event/push/alert/circonus?integration_key=<your_key>&format=json
    ```

    <Warning>
      `format=json` is required. Circonus sends JSON only when the URL contains `?format=json`; otherwise it sends a query string, which Flashduty cannot parse. The push URL already contains a `?`, so use `&` here.
    </Warning>
  </Step>

  <Step title="Assign the contact group to severities">
    Contact groups are configured per alert severity (1 to 5). In the rules of the ruleset, assign the contact group to every severity you want to be notified about, so that recovery notifications reach the same group.
  </Step>

  <Step title="Verify the lifecycle">
    Let a rule fire and confirm Flashduty shows an active alert, then let the metric return to normal and confirm the alert recovers. The webhook body has a fixed format; Circonus does not support custom alert formats for webhooks.
  </Step>
</Steps>

## Alert Key

***

Flashduty uses the `alert_id` of each alert as the Alert Key. The Circonus alert link has the form `...fault-detection?alert_id=<id>`, and a recovery notification carries all fields of the original alert plus `clear_value` and `clear_time`, so the trigger and the recovery share one `alert_id`.

The `alerts` array of one request can hold several alerts; each becomes its own Flashduty event. Changes to the rule, metric, severity, value, or time never change the Alert Key. A request whose alert has no `alert_id` is rejected, because a later recovery could not be matched.

## Status and severity

***

Circonus severities run from 1 to 5, where 1 is the most severe.

| Circonus `severity` | Flashduty severity |
| :- | :- |
| `1`, `2` | Critical |
| `3` | Warning |
| `4`, `5` | Info |
| Empty or any other value | Warning |

A notification with `clear_time` or `clear_value` is treated as a recovery and keeps the original severity. A body with no `alerts`, or an empty `alerts` array, returns success and creates no alert.

## Troubleshooting

***

* **Flashduty returns an invalid-parameter error**: check that the URL ends with `&format=json` and that every alert has a non-empty `alert_id`
* **The alert does not recover**: check that the contact group is assigned to that severity of the rule and that Circonus has cleared the alert; the recovery must carry the same `alert_id` as the trigger
* **No notification arrives**: check the ruleset wait time (Circonus creates the alert in its UI first and notifies contact groups only after the configured number of minutes), maintenance windows, and whether the contact group is assigned to that severity

For field details, see the [Circonus contact group documentation](https://docs.circonus.com/circonus/alerts/contact-groups/).