> ## 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.

# Sematext alert integration

> Send metric, log, Heartbeat, Experience and Synthetics alerts from Sematext Cloud to Flashduty On-call through a Custom notification hook.

Use a Custom notification hook in Sematext Cloud to send alert rule notifications to Flashduty On-call. Each alert rule (or each group of the rule when it uses Group by) maps to one Flashduty alert: the alert triggers when the rule fires and recovers automatically when Sematext sends the back-to-normal notification.

<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 **Sematext**, 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 **Sematext** 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 Sematext

***

<Steps>
  <Step title="Create a Custom notification hook">
    1. Sign in to Sematext Cloud (US region `apps.sematext.com` or EU region `apps.eu.sematext.com`) and select **Alerts** → **Notification Hooks** in the left menu
    2. Click **New Notification Hook**, then click the **Custom** card
    3. Set **Hook Name** to `Flashduty`
    4. Paste the full Flashduty push URL into **URL**. The URL must include `integration_key`
    5. Set **Send data as** to **Json** and **HTTP method** to **Post**
    6. Click **Add parameter** and add each parameter in the table below. The left column is the parameter name and the right column is its value; Sematext replaces the `$` variables when it sends the notification

    | Parameter name    | Value              |
    | :---------------- | :----------------- |
    | `backToNormal`    | `$backToNormal`    |
    | `priority`        | `$priority`        |
    | `ruleType`        | `$ruleType`        |
    | `description`     | `$description`     |
    | `applicationId`   | `$applicationId`   |
    | `createTimestamp` | `$createTimestamp` |
    | `troubleshootUrl` | `$troubleshootUrl` |

    When you are done, the request body in **Preview** should be:

    ```json theme={null}
    {
      "backToNormal": "$backToNormal",
      "priority": "$priority",
      "ruleType": "$ruleType",
      "description": "$description",
      "applicationId": "$applicationId",
      "createTimestamp": "$createTimestamp",
      "troubleshootUrl": "$troubleshootUrl"
    }
    ```

    7. Click **Send Test Notification** and confirm that the request succeeds, then click **Save Notification Hook**

    <Warning>
      Do not add `$applicationToken`. Anyone who has the App token can read the data in that App, and Flashduty does not need it.
    </Warning>
  </Step>

  <Step title="Use the hook in alert rules">
    1. Open the alert rule you want to connect (**Alerts** → **Alert Rules**) and go to the **Notifications** tab of the edit page
    2. Turn on **Alert me when the value goes back to non-alert level**. It is off by default; without it Sematext never sends the back-to-normal notification and the Flashduty alert does not recover
    3. Select the `Flashduty` hook in the **Additionally send to** drop-down and save the rule. When **Use account-default notification hooks for this alert** is off, the drop-down is named **Send to**

    To send every new alert rule to Flashduty, set the hook as an account-default hook.
  </Step>

  <Step title="Verify">
    1. Make an alert rule fire. For example, create a Heartbeat alert for a host and stop the Sematext Agent on it, then confirm that Flashduty receives an active alert
    2. Resume data collection, wait for Sematext to send the back-to-normal notification, and confirm that the alert recovers
  </Step>
</Steps>

<Warning>
  Sematext sends the back-to-normal notification only when the rule still receives data for that group and the value is back within the threshold. A Group by group that stops reporting data never gets one: for example, a log count rule grouped by host, where the host stops writing logs. Its Flashduty alert stays active until you close it. To detect a host that goes silent, use a Heartbeat alert.
</Warning>

<Note>
  The request sent by **Send Test Notification** does not belong to any alert rule. Flashduty returns success and does not create an alert.
</Note>

## Alert Key

***

Sematext adds the alert rule ID (`ruleId`) and rule name (`alertName`) to every alert notification. When the rule uses Group by, it also adds the group tag values that fired the alert (`filters`, for example `{os.host=web-01}`). You do not need to configure these fields in the hook.

The Alert Key is computed from `ruleId` and all group tags in `filters`; the order of the tags does not matter. As a result:

* Trigger and recovery notifications for the same alert rule and group go to the same alert
* When an alert rule is grouped by a tag such as host, each group gets its own alert
* Changes to the priority, description, time or rule name do not change the Alert Key

Requests that carry `alertName` but no `ruleId` are rejected.

## Status and severity

***

The alert recovers when `backToNormal` is `true`; any other value is treated as a trigger. The severity comes from the alert rule priority (`$priority`):

| Sematext priority        | Flashduty severity |
| :----------------------- | :----------------- |
| `CRITICAL`               | Critical           |
| `ERROR`                  | Critical           |
| `WARN`                   | Warning            |
| `INFO`                   | Info               |
| Empty or any other value | Warning            |

Matching ignores case.

## Labels

***

| Label                                                       | Source                                                                                                      |
| :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `check`                                                     | Alert rule name (`alertName`)                                                                               |
| `rule_id`                                                   | Alert rule ID (`ruleId`)                                                                                    |
| `rule_type`                                                 | Alert rule type (`ruleType`), such as `HEARTBEAT`, `AF_VALUE`, `LOGSENE_VALUE` or `SYNTHETICS_RESULT_VALUE` |
| `priority`                                                  | Original priority in Sematext                                                                               |
| `application_id`                                            | Sematext App ID                                                                                             |
| `filters`                                                   | Group tags as sent by Sematext                                                                              |
| Group tags, such as `os_host` (`os_host_raw` for Logs Apps) | Each tag in `filters`; characters such as `.` in the tag name are replaced with `_`                         |
| `troubleshoot_url`                                          | Link to the alert details page in Sematext                                                                  |
| `create_timestamp`                                          | Creation time of the alert notification, as a Unix timestamp in milliseconds                                |

## Troubleshooting

***

* **Flashduty returns a parameter error**: Make sure the URL is complete and includes `integration_key`, and that **Send data as** is set to **Json**
* **The alert does not recover**: Make sure **Alert me when the value goes back to non-alert level** is on in the rule's **Notifications** tab, that the hook has the `backToNormal` parameter with the value `$backToNormal`, and that the group is still sending data
* **Alerts for different hosts of the same rule are merged**: Set Group by on a host tag (such as `os.host`) in the alert rule and set the aggregation to all separately
* **Every alert has the Warning severity**: Check `priority` in the pushed content; see Status and severity above

For the meaning of each variable, see [Sematext Custom Webhooks Parameters](https://sematext.com/docs/integration/alerts-webhooks-custom-params/).