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.

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.

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 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. Example: “resource”: “171.26.23.22”, “check”: “api latency > 500ms”
images	No	[]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. 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 description, returned only when an error occurs
data	No	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 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:

{
  "alert_name": "CPU usage high",
  "status": "firing",
  "severity": "high",
  "host": "web-01",
  "tags": {
    "env": "production",
    "service": "api"
  }
}

Configure the following field mapping:

{
  "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:

{
  "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

---