> ## 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.
# IBM Instana alert integration
> Send IBM Instana issues, incidents, and changes to Flashduty On-call through a Generic webhook alert channel.
Use an IBM Instana Generic webhook alert channel to send Instana issues, incidents, and changes to Flashduty On-call. Each Instana issue or incident maps to one Flashduty alert: the alert triggers when the issue opens and recovers when the issue closes.
## 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 **Instana**, 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 **Instana** 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**
## Configure Instana
***
You need permission to configure alert channels and alerts in Instana. First create an alert channel that points to Flashduty, then select that channel in your alert configurations.
1. In Instana, click **Settings** → **Global settings**, then select **Alert channels** under **Events & alerts**. In some versions the path is **Settings** → **Team settings** → **Alert channels**
2. Click **Add alert channel**, select **Generic webhook** in the dialog, then click **Add alert channel** at the bottom of the dialog
3. Enter a **Name**, for example `Flashduty`
4. Paste the full Flashduty push URL into **Webhook URLs**. The URL must include `integration_key`
5. Leave **HTTP request headers** and OAuth empty. Flashduty authenticates the request by the `integration_key` in the URL
6. Click **Test channel** to check that Instana can reach Flashduty. Instana shows **Test Successful** when it can. The test notification does not create an alert in Flashduty
7. Click **Create**
1. Click **Settings** → **Alerts** → **New alert** and enter an alert name
2. In the **Events** drop-down, select **Alert on event type(s)**, then turn on the event types to send:
| Instana event type | What is sent | Effect in Flashduty |
| :------------------------------- | :-------------------------------------------------------- | :---------------------------------------------------------------------- |
| Incidents | `type` is `incident`, with state `OPEN` / `CLOSED` | Triggers when opened, recovers when closed |
| Critical issues / Warning issues | `type` is `issue`, with state `OPEN` / `CLOSED` | Triggers when opened, recovers when closed |
| Monitoring issues | `type` is `monitoringIssue`, with state `OPEN` / `CLOSED` | Triggers when opened, recovers when closed |
| Changes | `type` is `change`, no state | Each delivery creates an Info alert that does not recover automatically |
| Online / Offline | `type` is `presence`, no state | Each delivery creates an Info alert that does not recover automatically |
Changes and online/offline events are frequent and do not recover automatically. In most cases, turning on **Incidents**, **Critical issues**, and **Warning issues** is enough.
3. Under **Scope**, choose the required **Apply on** range: an application perspective, a Dynamic Focus query (Selected entities only), or All available entities
4. Under **Alerting**, click **Add alert channels** and select the channel you created in the previous step
5. (Optional) Under **Custom payloads**, add key-value pairs. They arrive in Flashduty as labels
6. Click **Create**
Smart Alerts for applications, websites, and synthetic tests select their alert channels in their own alert configuration. Select the same channel there.
1. Trigger an Instana issue and confirm that Flashduty receives an active alert. On a host running the Instana agent, you can send a critical event with a duration through the agent's Event SDK:
```bash theme={null}
curl -X POST http://localhost:42699/com.instana.plugin.generic.event \
-H 'Content-Type: application/json' \
-d '{"title":"Flashduty test","text":"Flashduty test","severity":10,"duration":300000}'
```
2. Wait for the issue to close in Instana (after 5 minutes in this example) and confirm that the alert recovers
An issue raised right after you save the alert configuration may not be delivered. Wait a few minutes after saving before you trigger one.
## Alert Key
***
Flashduty uses the Instana issue ID (`issue.id`) as the Alert Key. An issue or incident carries the same `issue.id` when it opens and when it closes, so the close notification recovers the alert created when it opened.
Changes to the issue title, severity, start time, or tags do not change the Alert Key. Requests without `issue.id` are rejected.
## Status and severity
***
Flashduty sets the alert severity from the issue's severity (`issue.severity`):
| Instana severity | Flashduty severity |
| :----------------------------------------------------- | :----------------- |
| `10` (Critical) | Critical |
| `5` (Warning) | Warning |
| `-1`, other, or empty (changes, online/offline events) | Info |
`issue.state` sets the status:
| `issue.state` | Status |
| :------------------------------------- | :---------------------------------------------------------------------------- |
| `OPEN` | Trigger |
| `CLOSED` | Recover, keeping the severity the alert had when it opened |
| Empty (changes, online/offline events) | Trigger. The alert does not recover automatically and must be closed manually |
Any other state value is rejected with a parameter error.
## Labels
***
| Label | Source |
| :------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_id` | Issue ID, which is the Alert Key |
| `issue_type` | Event type: `issue`, `incident`, `monitoringIssue`, `change`, or `presence` |
| `state` | `OPEN` or `CLOSED` |
| `instana_severity` | Original Instana severity |
| `resource` / `entity_label` | Name of the affected entity |
| `entity` / `entity_type` | Type of the affected entity, such as `jvm` or `Host` |
| `host` | FQDN of the affected host |
| `service` | Affected service |
| `zone` / `custom_zone` / `availability_zone` | Zone of the entity |
| `tags` | Tags of the entity |
| `container` | Affected container |
| `link` | Link to the issue in Instana |
| `custom_*` | Custom payloads from the alert configuration. For example, `custom:team` becomes `custom_team`, and multiple values are joined with commas |
Instana fills fields that do not apply with `not available`. Those fields do not become labels.
## Troubleshooting
***
* **Test channel reports that the domain is not allowed**: Instana SaaS may restrict the domains alert channels can send to. Contact IBM Instana support to allow the domain of the Flashduty push URL
* **Flashduty returns a parameter error**: Make sure the URL is complete and includes `integration_key`
* **The alert does not recover**: Make sure the alert configuration sends issues or incidents, which carry a state. Changes and online/offline events do not recover automatically
* **Real issues are not delivered**: Check the event types and scope of the alert configuration, and make sure the alert is linked to the channel
For field details, see [Instana Webhook alert channel](https://www.ibm.com/docs/en/instana-observability/current?topic=alerting-webhooks).