Overview
The Mapping labels rule type requires the Pro plan; the console marks it PRO.
- Flashduty receives an alert event
- The system sends event information and the list of expected labels to your API based on configuration
- Your API queries external data sources (such as CMDB, databases)
- The API returns the computed enrichment labels
- Flashduty attaches the returned labels to the alert
Setup steps
1
Implement the label mapping endpoint in your system
Where: Your service › an HTTP endpoint reachable by Flashduty
The endpoint must respond within the timeout you set in step 2 (1–3 seconds). For the full request and response fields and examples, see “API specification” below.
2
Create the mapping API in Flashduty
Where: Configuration › Mappings › API › Create API
Each account can create up to 50 APIs. Creating a mapping table schema also requires the Pro plan.
3
Add a mapping rule to the integration
Where: Flashduty console › Integration Center › Alert Events (dedicated integration: Flashduty console › Channels › Configuration › Integrations › Private integration)In the integration list on the right, open the integration that will use the mapping, then go to Label enrichment › Add label rule and choose Mapping labels as the rule type.When configuring label enrichment rules, you only need to focus on the following settings:
4
Push a test event and confirm the labels
Where: The detail page of the alert generated by the event, in the Flashduty consolePush an event that satisfies the rule’s conditions to the integration, then look in the alert details for the labels: the
result_labels your endpoint returned. If the endpoint fails (timeout, 404, 5xx), the alert is processed as usual without the enrichment labels, and the system may retry according to the retry count.API specification
Request method
POST, Content-Type:“application/json”
Request payload:
Event:
Image:
Request example
Response specification
Successful Response:Failure Response:
- HTTP Status Code:
200 OK - Response body must be a JSON object containing the
result_labelsfield - Keys in
result_labelsmust be label names specified in the request’sresult_label_keys - If a label cannot be retrieved, it should not be included in the response
Note: Returning200 OKstatus code with an emptyresult_labels: {}object will also be treated as “no results”, but using the404status code is the more standard approach.
Header security constraints
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.Header best practices
- Allowlist Mode: It is recommended to only allow custom Headers prefixed with
X-Custom-orX-Enrich- - Length Limits: The Key or Value length of a single Header should not exceed 1024 bytes
- Format Validation: Header Values must not contain line breaks (
\r,\n) to prevent Header injection attacks
Best practices
- 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.
-
Clear Error Handling: Make good use of HTTP status codes (especially
404) to convey clear execution results. -
Idempotency: The API design should be as idempotent as possible. Multiple calls for the same
eventshould return the same result. -
Security: The API must be protected through authentication and authorization mechanisms. Using custom Headers (for example,
X-Custom-Auth) for passing authentication information is recommended.
FAQ
-
Is there a response timeout for the service?
- The service must respond within the configured timeout period; exceeding this is considered a failure
-
What happens if the API returns a failure?
- The alert will be processed normally, but no enrichment labels will be attached
- Based on the configured retry count, the system may retry the request
-
Can result_label_keys be changed dynamically?
- Yes, you can modify the list of expected labels in Flashduty at any time without modifying the API code