Label Mapping API

I. Overview

The Label Mapping API allows you to build custom external services to enrich alert labels. The workflow is as follows:

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, etc.)
The API returns the computed enrichment labels
Flashduty attaches the returned labels to the alert

II. API Specification

Request Method

POST, Content-Type:“application/json”

Request Payload:

Field	Type	Required	Description
result_label_keys	[]string	Yes	List of expected label keys to return, configured by users in Flashduty
event	Event	Yes	Complete information of the current alert event

Event:

Field	Type	Required	Description
account_id	int64	Yes	Account ID
channel_id	int64	Yes	Channel ID
data_source_id	int64	Yes	Data source ID
data_source_type	string	Yes	Data source type, e.g., prometheus, zabbix, etc.
title	string	Yes	Alert title
title_rule	string	No	Title rule
description	string	No	Alert description
alert_key	string	Yes	Alert unique identifier
alert_id	string	Yes	Alert ID
event_severity	string	Yes	Event severity, enum: Critical, Warning, Info
event_status	string	Yes	Event status, enum: Critical, Warning, Info, Ok
event_time	int64	Yes	Event time, Unix timestamp in seconds
labels	map[string]string	No	Alert original label key-value pairs
images	[]string	No	List of alert-related images

Request Example

{
  "result_label_keys": ["owner_team", "service_tier", "host_ip"],
  "event": {
    "account_id": 1,
    "channel_id": 20,
    "data_source_id": 15,
    "data_source_type": "prometheus",
    "description": "CPU usage for instance '10.0.1.101:9100' is over 95%",
    "title": "High CPU Usage on instance 10.0.1.101:9100",
    "title_rule": "",
    "alert_key": "d41d8cd98f00b204e9800998ecf8427e",
    "alert_id": "62d6c0f6b8f1b2b3c4d5e6f7",
    "event_severity": "Critical",
    "event_status": "Critical",
    "event_time": 1678886400,
    "labels": {
      "region": "us-east-1",
      "service": "service-A",
      "env": "production",
      "instance": "10.0.1.101:9100"
    },
    "images": []
  }
}

Response Specification

Successful Response:

Field	Type	Required	Description
result_labels	map[string]string	Yes	Returned enrichment label key-value object

HTTP Status Code: 200 OK
Response body must be a JSON object containing the result_labels field
Keys in result_labels must be label names specified in the request’s result_label_keys
If a label cannot be retrieved, it should not be included in the response

Successful Response Example:

{
  "result_labels": {
    "owner_team": "team-database",
    "service_tier": "tier-1",
    "host_ip": "10.0.1.101"
  }
}

Failure Response:

Status Code	Meaning
404 Not Found	No data available for enrichment based on the event information
400 Bad Request	Request body format error or event object missing required fields
5xx	Unexpected internal API error (e.g., database connection failure)

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.

III. Configure Mapping Service

When configuring label mapping in Flashduty, you need to first create a mapping service, then reference that service in your label enrichment rules.

Mapping Service Field Description

Field	Type	Required	Description
api_name	string	Yes	Human-readable service name for selection and reference in the UI, e.g., “CMDB Asset Query API”
description	string	No	Detailed description of the service
url	string	Yes	API request URL, supports template variables
headers	map[string]string	No	HTTP request headers for passing custom authentication, subject to security blacklist restrictions
timeout	int	No	Request timeout (in seconds)，scope: 1~3
retry_count	int	No	Number of retries after request failure, ，scope: 0~1
insecure_skip_verify	bool	No	Skip certificate verification for HTTPS requests
status	string	No	Service status, e.g., enabled, disabled

Label Enrichment Rule Configuration

When configuring label enrichment rules, you only need to focus on the following settings:

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
Mapping Service: Select or configure the API service URL, Headers, and other information

IV. 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.

Category	Blacklisted Headers	Risk Description
Authentication & Authorization	`authorization`, `proxy-authorization`, `cookie`, `x-api-key`, `x-access-token`	Prevents credential leakage or unauthorized hijacking of existing authentication contexts
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
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
Protocol & Request Smuggling	`transfer-encoding`, `upgrade`, `connection`	Prevents request smuggling attacks exploiting HTTP protocol differences

Header Best Practices

Allowlist Mode: It is recommended to only allow custom Headers prefixed with X-Custom- or X-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

V. 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 event should return the same result.
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.

VI. 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

Quick Start

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

I. Overview

II. API Specification

Request Method

Request Payload:

Request Example

Response Specification

III. Configure Mapping Service

Mapping Service Field Description

Label Enrichment Rule Configuration

IV. Header Security Constraints

Header Best Practices

V. Best Practices

VI. FAQ

​I. Overview

​II. API Specification

​Request Method

​Request Payload:

​Request Example

​Response Specification

​III. Configure Mapping Service

​Mapping Service Field Description

​Label Enrichment Rule Configuration

​IV. Header Security Constraints

​Header Best Practices

​V. Best Practices

​VI. FAQ

I. Overview

II. API Specification

Request Method

Request Payload:

Request Example

Response Specification

III. Configure Mapping Service

Mapping Service Field Description

Label Enrichment Rule Configuration

IV. Header Security Constraints

Header Best Practices

V. Best Practices

VI. FAQ