Label Mapping API

​

I. Overview

1. Flashduty receives an alert event
2. The system sends event information and the list of expected labels to your API based on configuration
3. Your API queries external data sources (such as CMDB, databases, etc.)
4. The API returns the computed enrichment labels
5. Flashduty attaches the returned labels to the alert

​

II. API Specification

​

Request Method

​

Request Payload:

​

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

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

​

III. Configure Mapping Service

​

Mapping Service Field Description

​

Label Enrichment Rule Configuration

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

​

IV. Header Security Constraints

​

Header Best Practices

1. Allowlist Mode: It is recommended to only allow custom Headers prefixed with X-Custom- or X-Enrich-
2. Length Limits: The Key or Value length of a single Header should not exceed 1024 bytes
3. Format Validation: Header Values must not contain line breaks (\r, \n) to prevent Header injection attacks

​

V. Best Practices

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.
2. Clear Error Handling: Make good use of HTTP status codes (especially 404) to convey clear execution results.
3. Idempotency: The API design should be as idempotent as possible. Multiple calls for the same event should return the same result.
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.

​

VI. FAQ

1. Is there a response timeout for the service?
   • The service must respond within the configured timeout period; exceeding this is considered a failure
2. 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
3. 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