Skip to main content

Overview

The Mapping labels rule type requires the Pro plan; the console marks it PRO.
The Label Mapping API allows you to build custom external services to enrich alert labels. The workflow is as follows:
  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)
  4. The API returns the computed enrichment labels
  5. 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 FlashdutyThe 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 APIEach 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:
  • 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:
Failure Response:
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.

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

  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

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 (for example, X-Custom-Auth) for passing authentication information is recommended.

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