Skip to content

Commit a45f42f

Browse files
alick-limingniuweili
alick-liming
authored and
niuweili
committed
feat: add enrich mapping api
1 parent cdafb4c commit a45f42f

2 files changed

Lines changed: 423 additions & 0 deletions

File tree

‎flashduty/en/1. On-call/8. Integrations/8.5 Webhooks/8.5.7 Label Mapping API.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
Configure Label Mapping API to automatically call your external API when alert events arrive, enabling dynamic enrichment and correlation of alert information. With this feature, you can automatically attach information from external data sources such as CMDB, HR systems, and more to your alerts.
2+
3+
## I. Overview
4+
5+
The Label Mapping API allows you to build custom external services to enrich alert labels. The workflow is as follows:
6+
7+
1. Flashduty receives an alert event
8+
2. The system sends event information and the list of expected labels to your API based on configuration
9+
3. Your API queries external data sources (such as CMDB, databases, etc.)
10+
4. The API returns the computed enrichment labels
11+
5. Flashduty attaches the returned labels to the alert
12+
13+
<span id="ApiSpec"></span>
14+
15+
## II. API Specification
16+
17+
### Request Method
18+
19+
<div class="md-block">
20+
21+
POST, Content-Type:"application/json"
22+
23+
</div>
24+
25+
### Request Payload:
26+
27+
<div class="md-block">
28+
29+
| Field | Type | Required | Description |
30+
| :--------: | :-------------------: | :--: | :--------- |
31+
| result_label_keys | []string | Yes | List of expected label keys to return, configured by users in Flashduty |
32+
| event | [Event](#Event) | Yes | Complete information of the current alert event |
33+
34+
<span id="Event"></span>
35+
**Event**:
36+
37+
| Field | Type | Required | Description |
38+
| :--------: | :-------------------: | :--: | :--------- |
39+
| account_id | int64 | Yes | Account ID |
40+
| channel_id | int64 | Yes | Channel ID |
41+
| data_source_id | int64 | Yes | Data source ID |
42+
| data_source_type | string | Yes | Data source type, e.g., prometheus, zabbix, etc. |
43+
| title | string | Yes | Alert title |
44+
| title_rule | string | No | Title rule |
45+
| description | string | No | Alert description |
46+
| alert_key | string | Yes | Alert unique identifier |
47+
| alert_id | string | Yes | Alert ID |
48+
| event_severity | string | Yes | Event severity, enum: Critical, Warning, Info |
49+
| event_status | string | Yes | Event status, enum: Critical, Warning, Info, Ok |
50+
| event_time | int64 | Yes | Event time, Unix timestamp in seconds |
51+
| labels | map[string]string | No | Alert original label key-value pairs |
52+
| images | []string | No | List of alert-related images |
53+
54+
</div>
55+
56+
### Request Example
57+
58+
<div class="md-block">
59+
60+
```json
61+
{
62+
"result_label_keys": ["owner_team", "service_tier", "host_ip"],
63+
"event": {
64+
"account_id": 1,
65+
"channel_id": 20,
66+
"data_source_id": 15,
67+
"data_source_type": "prometheus",
68+
"description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
69+
"title": "High CPU Usage on instance 10.0.1.101:9100",
70+
"title_rule": "",
71+
"alert_key": "d41d8cd98f00b204e9800998ecf8427e",
72+
"alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
73+
"event_severity": "Critical",
74+
"event_status": "Critical",
75+
"event_time": 1678886400,
76+
"labels": {
77+
"region": "us-east-1",
78+
"service": "service-A",
79+
"env": "production",
80+
"instance": "10.0.1.101:9100"
81+
},
82+
"images": []
83+
}
84+
}
85+
```
86+
87+
</div>
88+
89+
### Response Specification
90+
91+
<div class="md-block">
92+
93+
**Successful Response:**
94+
95+
| Field | Type | Required | Description |
96+
| :--------: | :-------------------: | :--: | :--------- |
97+
| result_labels | map[string]string | Yes | Returned enrichment label key-value object |
98+
99+
- HTTP Status Code: `200 OK`
100+
- Response body must be a JSON object containing the `result_labels` field
101+
- Keys in `result_labels` must be label names specified in the request's `result_label_keys`
102+
- If a label cannot be retrieved, it **should not** be included in the response
103+
104+
**Successful Response Example:**
105+
106+
```json
107+
{
108+
"result_labels": {
109+
"owner_team": "team-database",
110+
"service_tier": "tier-1",
111+
"host_ip": "10.0.1.101"
112+
}
113+
}
114+
```
115+
116+
**Failure Response:**
117+
118+
| Status Code | Meaning |
119+
| :--------: | :--------- |
120+
| 404 Not Found | No data available for enrichment based on the event information |
121+
| 400 Bad Request | Request body format error or event object missing required fields |
122+
| 5xx | Unexpected internal API error (e.g., database connection failure) |
123+
124+
> **Note:** Returning `200 OK` status code with an empty `result_labels: {}` object will also be treated as "no results", but using the `404` status code is the more standard approach.
125+
126+
</div>
127+
128+
<span id="ServiceConfig"></span>
129+
130+
## III. Configure Mapping Service
131+
132+
When configuring label mapping in Flashduty, you need to first create a mapping service, then reference that service in your label enrichment rules.
133+
134+
### Mapping Service Field Description
135+
136+
<div class="md-block">
137+
138+
| Field | Type | Required | Description |
139+
| :--------: | :-------------------: | :--: | :--------- |
140+
| api_name | string | Yes | Human-readable service name for selection and reference in the UI, e.g., "CMDB Asset Query API" |
141+
| description | string | No | Detailed description of the service |
142+
| url | string | Yes | API request URL, supports template variables |
143+
| headers | map[string]string | No | HTTP request headers for passing custom authentication, subject to [security blacklist](#HeaderBlacklist) restrictions |
144+
| timeout | int | No | Request timeout (in seconds)，scope: 1~3 |
145+
| retry_count | int | No | Number of retries after request failure, ，scope: 0~1 |
146+
| insecure_skip_verify | bool | No | Skip certificate verification for HTTPS requests |
147+
| status | string | No | Service status, e.g., enabled, disabled |
148+
149+
</div>
150+
151+
### Label Enrichment Rule Configuration
152+
153+
When configuring label enrichment rules, you only need to focus on the following settings:
154+
155+
1. **result_label_keys**: Specify the list of labels you expect to retrieve from the API. Flashduty will automatically combine this list with the current `event` object into a request body and send it to your API
156+
2. **Mapping Service**: Select or configure the API service URL, Headers, and other information
157+
158+
<span id="HeaderBlacklist"></span>
159+
160+
## IV. Header Security Constraints
161+
162+
To prevent security bypasses, request smuggling, IP spoofing, and cache poisoning, the following Headers are **prohibited** when customizing API request headers. The system gateway will automatically filter or reject requests containing these Headers.
163+
164+
<div class="md-block">
165+
166+
| Category | Blacklisted Headers | Risk Description |
167+
| :--- | :--- | :--- |
168+
| **Authentication & Authorization** | `authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token` | Prevents credential leakage or unauthorized hijacking of existing authentication contexts |
169+
| **IP & Geolocation Spoofing** | `x-forwarded-for`, `x-real-ip`, `true-client-ip`, `x-client-ip` | Prevents clients from spoofing source IP to bypass rate limits or allowlists/blocklists |
170+
| **Host & Routing Manipulation** | `host`, `x-forwarded-host`, `x-forwarded-proto`, `x-internal-id`, `x-user-id` | Prevents Host injection attacks, redirect loops, or spoofing internal system IDs |
171+
| **Protocol & Request Smuggling** | `transfer-encoding`, `upgrade`, `connection` | Prevents request smuggling attacks exploiting HTTP protocol differences |
172+
173+
</div>
174+
175+
### Header Best Practices
176+
177+
1. **Allowlist Mode**: It is recommended to only allow custom Headers prefixed with `X-Custom-` or `X-Enrich-`
178+
2. **Length Limits**: The Key or Value length of a single Header should not exceed 1024 bytes
179+
3. **Format Validation**: Header Values must not contain line breaks (`\r`, `\n`) to prevent Header injection attacks
180+
181+
## V. Best Practices
182+
183+
1. **Performance First:** This API is on the critical path of alert processing and must ensure low latency. Queries to external data sources should be as fast as possible, and implementing caching is recommended.
184+
185+
2. **Clear Error Handling:** Make good use of HTTP status codes (especially `404`) to convey clear execution results.
186+
187+
3. **Idempotency:** The API design should be as idempotent as possible. Multiple calls for the same `event` should return the same result.
188+
189+
4. **Security:** The API must be protected through authentication and authorization mechanisms. Using custom Headers (e.g., `X-Custom-Auth`) for passing authentication information is recommended.
190+
191+
## VI. FAQ
192+
193+
1. **Is there a response timeout for the service?**
194+
195+
- The service must respond within the configured timeout period; exceeding this is considered a failure
196+
197+
2. **What happens if the API returns a failure?**
198+
199+
- The alert will be processed normally, but no enrichment labels will be attached
200+
- Based on the configured retry count, the system may retry the request
201+
202+
3. **Can result_label_keys be changed dynamically?**
203+
204+
- Yes, you can modify the list of expected labels in Flashduty at any time without modifying the API code
205+
206+
4. **How do I secure my API?**
207+
208+
- It's recommended to add an `Authorization` header in the mapping service configuration
209+
- You can verify the request source IP on the API side
210+
- Using HTTPS for encrypted transmission is recommended
211+

0 commit comments

Comments
 (0)