> ## 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.
# Standard Alert Event Integration Guide
> Push alert events from your own system to Flashduty through standard protocols to achieve automated alert noise reduction.
Push alert events from your own system to Flashduty through standard protocols to achieve automated alert noise reduction.
:::tips
Flashduty has already adapted webhook protocols for most common alert systems. For these systems, you should first use the corresponding integration for simplicity. This integration provides a standard HTTP interface that requires your development for adaptation. The advantage is that you can push any alert events you want to handle through On-call.
:::
## Steps
***
### In Flashduty
You can obtain an integration push URL through either of the following two methods:
#### Using Dedicated Integration
When you don't need to route alert events to different collaboration spaces, this method is preferred as it's simpler.
Expand
1. Enter the Flashduty console, select **Collaboration Space**, and enter the details page of a space
2. Select the **Integrations** tab, click **Add Integration**, and enter the add integration page
3. Select **Standard Alert Event** integration, click **Save** to generate a card
4. Click the generated card to view the **Push URL**, copy it for later use, and you're done
#### Using Shared Integration
When you need to route alert events to different collaboration spaces based on the alert event's Payload information, this method is preferred.
Expand
1. Enter the Flashduty console, select **Integration Center => Alert Events** to enter the integration selection page
2. Select **Standard Alert Event** integration:
* **Integration Name**: Define a name for the current integration
3. Configure the default route and select the corresponding channel (after the integration is created, you can go to `Route` to configure more routing rules)
4. Click **Save** and copy the newly generated **push URL** for later use
5. Done
## I. Request Description
***
### Request Method
POST, Content-Type:"application/json"
### Request Parameters:
#### Headers:
| Field | Required | Type | Description |
| :----------: | :------: | :----: | :------------------------------ |
| Content-Type | Yes | string | Fixed value: `application/json` |
#### Query Strings:
| Field | Required | Type | Description |
| :--------------: | :------: | :----: | :--------------------------------------------------------------------- |
| integration\_key | Yes | string | Integration key for access control. Obtained after adding integration. |
#### Payload:
| Field | Required | Type | Description |
| :-----------: | :------: | :----------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title\_rule | Yes | string | Alert title, no more than `512` characters, will be truncated if exceeded. Supports dynamic title generation based on alert content, see [Customizing Incidents](https://docs.flashcat.cloud/zh/on-call/integration/alert-integration/alert-pipelines) for generation rules. |
| event\_status | Yes | string | Alert status. Enumerated values (case-sensitive): *Critical*, *Warning*, *Info*, *Ok*. When specified as Ok, it means automatic recovery of the alert. |
| alert\_key | No | string | Alert identifier, used to update or automatically recover existing alerts. You can customize this value, but it cannot exceed `255` characters. You can also rely on system auto-generation, this value will be returned in the response. If you're reporting a recovery event, this value must exist. |
| description | No | string | Alert description, no more than `2048` characters, will be truncated if exceeded. |
| labels | No | map | Alert label collection, key is the label name, value is the label value. 1. Both key and value of labels are string type, case-sensitive. 2. Label key should not exceed `128` characters, following Prometheus label naming conventions. Value should not exceed `2048` characters, will be truncated if exceeded. 3. Maximum of `50` labels. See `Label Content Reference` in [Best Practices](#best-practices). Example: "resource": "171.26.23.22", "check": "api latency > 500ms" |
| images | No | \[][image](#image) | Array of images, used for image display in frontend or Feishu/DingTalk application notifications.The system merged/overwritten based on alt, for the same alt (including empty strings), only one is retained |
#### image Structure
| Field | Required | Type | Description |
| :---: | :------: | :----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alt | No | string | Image alternative text, limit 128 characters, truncated if exceeded. |
| src | Yes | string | Image source, value: http/https URL or image\_key returned by [Image Upload API](/en/on-call/integration/alert-integration/alert-sources/image-upload). Limit 256 characters, discarded if exceeded |
| href | No | string | Hyperlink reference path, limit 256 characters, truncated if exceeded |
### Response
| Field Name | Required | Type | Description |
| :---------: | :------: | :-------------: | :---------------------------------------------------- |
| request\_id | Yes | string | Request ID for trace tracking |
| error | No | [Error](#Error) | Error description, returned only when an error occurs |
| data | No | [Data](#Data) | Report information |
Data:
| Field Name | Required | Type | Description |
| :--------: | :------: | :----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alert\_key | No | string | Alert identifier, can be used to report recovery events. If you specified an alert\_key when reporting the event, this value remains unchanged. Otherwise, it's automatically generated by the system. |
Error:
| Field Name | Required | Type | Description |
| :--------: | :------: | :----: | :-------------------------------------------------- |
| code | Yes | string | Error code, see [Code](#Code) for enumerated values |
| message | No | string | Error description |
Code:
| Error Code | HTTP Status | Description |
| :------------------: | :---------: | ---------------------------------------------------------------------------------------------------------- |
| InvalidParameter | 400 | Parameter error |
| InvalidContentType | 400 | Content-Type not supported |
| MethodNotAllowed | 400 | HTTP Method not supported |
| Unauthorized | 401 | Login authentication failed |
| AccessDenied | 403 | Permission authentication failed |
| RequestTooFrequently | 429 | Request too frequent |
| RouteNotFound | 404 | Request Method+Path not matched |
| ResourceNotFound | 400 | Account hasn't purchased resources, please go to the cost center to place an order |
| NoLicense | 400 | Account has insufficient subscription licenses, please upgrade or purchase subscription in the cost center |
| InternalError | 500 | Internal or unknown error |
### II. Request Example
***
Request:
```
curl -X POST '{api_host}/event/push/alert/standard?integration_key={integration_key}' \
-H 'Content-Type: application/json' \
-d '{
"event_status": "Warning",
"title_rule": "cpu idle low than 20%",
"labels": {
"service": "engine",
"cluster":"nj",
"resource":"es.nj.01",
"check":"cpu.idle<20%",
"metric":"node_cpu_seconds_total"
}
}' -v
```
Successful Response:
```
{
"request_id": "0ace00116215ab4ca0ec5244b8fc54b0",
"data": {
"alert_key": "9qJ798NJoXS4UMVB5SHsNj"
}
}
```
Failed Response:
```
{
"request_id": "0ace00116215abc0ba4e52449bd305b0",
"error": {
"code": "InvalidParameter",
"message": "integration_key is not a valid one"
}
}
```
## III. Field Mapping and Value Mapping
***
If your system's JSON format cannot directly match the standard Payload structure above, you can configure **field mapping (field\_mapping)** and **value mapping (value\_mapping)** in the integration settings to let Flashduty automatically convert any JSON format into standard alert events.
Once field mapping is configured, the request body no longer requires a fixed format. It accepts any JSON object, and also supports batch push via JSON arrays (up to 100 items per request).
### Field mapping (field\_mapping)
Use `{{variable.path}}` syntax to reference fields from the original JSON and map them to target fields of the standard alert event.
Supported target fields:
| Target field | Description |
| :------------ | :-------------------------------------------- |
| title | Alert title |
| title\_rule | Alert title rule |
| description | Alert description |
| event\_status | Alert status (Critical / Warning / Info / Ok) |
| alert\_key | Alert identifier |
| labels | Alert labels |
| images | Image array |
**Variable syntax:**
* Use `.` to separate path levels, e.g. `{{data.severity}}` references a nested field
* When the entire value is a single variable (e.g. `"{{tags}}"`), the original data type is preserved (object, array, etc.)
* When a variable is mixed with other text (e.g. `"{{host}} - {{check}}"`), variables are converted to strings for concatenation
**Two ways to map labels:**
* **Wildcard expansion**: `"labels": "{{tags}}"` — expands all children of the `tags` object as labels
* **Per-label mapping**: `"labels": {"env": "{{tags.env}}", "host": "{{hostname}}"}` — maps each label individually
**Example:**
Your system pushes the following format:
```json theme={null}
{
"alert_name": "CPU usage high",
"status": "firing",
"severity": "high",
"host": "web-01",
"tags": {
"env": "production",
"service": "api"
}
}
```
Configure the following field mapping:
```json theme={null}
{
"title_rule": "{{alert_name}}",
"event_status": "{{severity}}",
"alert_key": "{{host}}::{{alert_name}}",
"description": "Host {{host}} alert: {{alert_name}}",
"labels": "{{tags}}"
}
```
### Value mapping (value\_mapping)
When your source system's field values differ from Flashduty's standard (e.g. using `high` instead of `Critical` for severity), configure value mapping for automatic conversion.
Value mapping is configured per **field path**, with each path containing a `source value → target value` mapping table.
**Example:**
```json theme={null}
{
"severity": {
"high": "Critical",
"medium": "Warning",
"low": "Info",
"resolved": "Ok"
}
}
```
Combined with the field mapping above, `"severity": "high"` in the original JSON is first extracted via field mapping, then converted to `Critical` via value mapping, and finally written to the `event_status` field.
All `{{...}}` variables must resolve to a value in the original JSON, otherwise the request will fail. It is recommended to test your mapping configuration with a small dataset first.
## IV. Best Practices
***
1. Send events to Flashduty when alert status changes
2. When an alert recovers, send an event with status Ok to close the alert. Otherwise, the alert will remain open. If your alert system doesn't have recovery events, we recommend manually sending recovery events
3. Labels are event descriptions, and label content should be as rich as possible (specified when sending, or generated through enrichment rules), such as:
* Alert source, like host, cluster, check, or metric
* Alert ownership information, like team, owner
* Alert category information, like class (api, db, net)
## V. FAQ
***
Why haven't I received alerts in Flashduty?
#### In Flashduty
1. Check if the integration shows **Latest Event Time**? If not, it means Flashduty hasn't received the push, prioritize checking your system.
2. If you're using **Shared Integration**, first confirm if you've configured **Routing Rules**. Without routing rules, the system will directly reject new pushes as there's no collaboration space to handle your alerts. In this case, simply configure routing rules to your desired space.
#### In Your System
1. Confirm that your request URL exactly matches the URL in the integration details.
2. Confirm that your service can access the external domain api.flashcat.cloud. If not, you need to enable external network access for the server or specifically for Flashduty's domain.
3. Print Flashduty service's response to check for clear information.
If you still can't find the root cause after these steps, please contact us with the **request\_id** from the request response.
Why was the push request successful but no new alerts or incidents were generated?
Flashduty uses a 2-layer noise reduction mechanism:
1. First, it checks for duplicate alert events. If your pushed event is identical to a previously pushed event, the new event will be discarded.
2. If the new event's status and description match the status, title, and description of the last event of its corresponding alert, the new event will be discarded while updating the alert's attributes.
3. The new event might be discarded due to matching exclusion, discard, suppression, or silence rules.
4. When a new event triggers a new alert, the system enters the second layer of noise reduction check, determining if the new alert can be merged into an active incident. If possible, it will only merge into the existing incident without generating a new one.
For more information, please refer to [Alert Noise Reduction](/en/on-call/channel/noise-reduction).