Webhook Custom Actions

Plan requirement: This feature requires an On-call Standard or higher subscription. Learn more

Configure incident custom actions, allowing you to quickly call external interfaces during incident troubleshooting to achieve self-healing, information enrichment, or any custom operations.

1. Create Action

Login to Flashduty console, go to Integration Center - Webhook
Click to add Custom Action integration
Configure Action Name—this name will appear as a button in incident details
Configure Managing Team—select the team that manages this integration; only team members can edit the integration configuration
Configure Channels—you can configure multiple, but each channel can have at most 5 Custom Actions
Configure Endpoint and custom Headers
TLS Verification is enabled by default. If the target service uses a self-signed certificate or a certificate issued by an internal CA, you can disable the TLS Verification toggle so the system will not validate the server certificate

Disabling TLS certificate verification may expose you to man-in-the-middle attacks. Only disable it in test environments or when using self-signed certificates.

Save to complete

Each channel can have a maximum of 5 custom actions. If a channel has reached this limit, it cannot be selected when adding a new custom action.

2. Push Description

Request Method

POST, Content-Type:“application/json”

Request Payload:

Field	Type	Required	Description
event_time	int64	Yes	Event timestamp in `milliseconds`
event_type	string	Yes	Event type, fixed value `i_custom`
event_id	string	Yes	Event ID, `the same event may retry multiple times due to timeout, receiver needs to deduplicate`
person	Person	No	Operator, only exists for human actions
incident	Incident	Yes	Incident details

Person:

Field	Type	Required	Description
person_id	int64	Yes	Person ID
person_name	string	Yes	Person name
email	string	Yes	Email address

Responder:

Field	Type	Required	Description
person_id	int64	Yes	Person ID
person_name	string	Yes	Person name
email	string	Yes	Email address
assigned_at	int64	No	Assignment time
acknowledged_at	int64	No	Acknowledgment time

Incident:

Field	Type	Required	Description
incident_id	string	Yes	Incident ID
title	string	Yes	Incident title
description	string	No	Incident description
impact	string	No	Incident impact
root_cause	string	No	Incident root cause
resolution	string	No	Incident resolution
incident_severity	string	Yes	Severity, enum: Critical, Warning, Info
incident_status	string	Yes	Incident status, enum: Critical, Warning, Info, Ok
progress	string	Yes	Progress, enum: Triggered, Processing, Closed
created_at	int64	Yes	Created time
updated_at	int64	Yes	Updated time
start_time	int64	Yes	Trigger time, Unix seconds timestamp
last_time	int64	No	Latest event time, latest event push time in associated alerts, Unix seconds timestamp, default 0
end_time	int64	No	Recovery time, incident auto-recovers when all associated alerts recover, Unix seconds timestamp, default 0
ack_time	int64	No	First acknowledgment time, incident can be acknowledged by multiple people, this is the earliest acknowledgment time. Unix seconds timestamp, default 0
close_time	int64	No	Close time, end_time represents incident recovery time, close_time represents progress close time, incident closes when recovered, closing doesn’t affect recovery. Unix seconds timestamp, default 0
snoozed_before	int64	No	Snooze deadline
labels	map[string]string	No	Label KV, both Key and Value are strings. Not present for manual creation, for auto creation it’s the labels of the first grouped alert
fields	map[string]interface	No	Custom field KV, Key is string, Value can be any type depending on field type
creator	Person	No	Creator info, only exists for manually created incidents
closer	Person	No	Closer info, only exists for manually closed incidents
responders	[]Responder	No	Responders list
alerts	Alert	No	Associated alerts
alert_cnt	int64	No	Associated alert count
num	string	Yes	Short incident identifier — the last 6 hex characters of the incident ObjectID, uppercased (e.g. `054D57`). Displayed in the console UI. Can be passed to the incident info API as an alternative to `incident_id` (either field is accepted; not unique within an account — the most recently created match is returned)
channel_id	int64	No	Channel ID, 0 means not belonging to any channel
channel_name	string	No	Channel name
team_id	int64	No	ID of the team that owns the channel; 0 when the channel has no owning team
detail_url	string	Yes	Detail URL
group_method	string	No	Grouping method, enum: n: no grouping, p: rule-based grouping, i: intelligent grouping

Alert:

Field	Type	Required	Description
alert_id	string	Yes	Alert ID
data_source_id	int64	Yes	Integration ID
title	string	Yes	Alert title
description	string	No	Alert description
alert_key	string	Yes	Alert association key
alert_severity	string	Yes	Severity, enum: Critical, Warning, Info
alert_status	string	Yes	Alert status, enum: Critical, Warning, Info, Ok
progress	string	Yes	Progress, enum: Triggered, Closed
created_at	int64	Yes	Created time
updated_at	int64	Yes	Updated time
start_time	int64	Yes	First trigger time (time of first event received by platform), Unix seconds timestamp
last_time	int64	Yes	Latest event time (time of latest event received by platform), Unix seconds timestamp
end_time	int64	No	Alert recovery time (time platform last received end-type event), Unix seconds timestamp, default 0
close_time	int64	No	Close time, different from end_time, this is progress close, doesn’t mean alert truly recovered. Unix seconds timestamp, default 0
labels	map[string]string	No	Label KV, both Key and Value are strings

Request Response

HTTP status code 200 indicates successful push.

Request Example

curl -X POST 'https://example.com/incident/action?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
    "event_time": 1700208013988,
    "event_type": "i_custom",
    "incident": {
        "event_id":"fac0599a2a25529ba2362c0c184b6cfb",
        "account_id": 74058170041504,
        "account_name": "TouTie Tech",
        "ack_time": 0,
        "alert_cnt": 1,
        "alerts": [
            {
                "account_id": 74058170041504,
                "alert_id": "6551f37f8713372ad1054d54",
                "alert_key": "asdflasdfl2xzasd112621",
                "alert_severity": "Critical",
                "alert_status": "Critical",
                "close_time": 0,
                "created_at": 1699869567,
                "data_source_id": 2398086111504,
                "description": "cpu.idle < 20%",
                "end_time": 0,
                "event_cnt": 0,
                "labels": {
                    "a": "a",
                    "check": "Custom field test",
                    "cluster": "nj",
                    "metric": "node_cpu_seconds_total",
                    "resource": "es.nj.01",
                    "service": "engine",
                    "v": "v"
                },
                "last_time": 1699869562,
                "progress": "Triggered",
                "responder_email": "",
                "responder_id": 0,
                "responder_name": "",
                "start_time": 1699869562,
                "title": "nj / es.nj.01 - Custom field test",
                "title_rule": "$cluster::$resource::$check",
                "updated_at": 1699869576
            }
        ],
        "assigned_to": {
            "assigned_at": 1699869576,
            "escalate_rule_id": "6509344bc1d50d723ca04986",
            "escalate_rule_name": "Policy 5",
            "id": "VobpBqvTuXgQ7BZzJ2Qu94",
            "layer_idx": 0,
            "type": "assign"
        },
        "channel_id": 1973372625504,
        "channel_name": "lim_test",
        "close_time": 0,
        "created_at": 1699869576,
        "data_source_id": 2398086111504,
        "dedup_key": "asdflasdfl2xzasd112621",
        "description": "cpu.idle < 20%",
        "detail_url": "http://10.206.0.17:8567/incident/detail/6551f3888713372ad1054d57",
        "end_time": 0,
        "equals_md5": "",
        "fields": {
            "impacted_services": [
                "passport",
                "order"
            ],
            "priority": "P3"
        },
        "group_method": "p",
        "impact": "",
        "incident_id": "6551f3888713372ad1054d57",
        "incident_severity": "Critical",
        "incident_status": "Critical",
        "labels": {
            "a": "a",
            "check": "Custom field test",
            "cluster": "nj",
            "metric": "node_cpu_seconds_total",
            "resource": "es.nj.01",
            "service": "engine",
            "v": "v"
        },
        "creator":{
            "email":"toutie@flashcat.cloud",
            "person_id":1552048792504,
            "person_name":"TouTie"
        },
        "last_time": 1699869562,
        "num": "054D57",
        "progress": "Triggered",
        "resolution": "",
        "responders": [
            {
                "acknowledged_at": 0,
                "assigned_at": 1699869576,
                "email": "zhangsan@toutie.com",
                "person_id": 1234648032504,
                "person_name": "zhangsan"
            }
        ],
        "root_cause": "",
        "snoozed_before": 0,
        "start_time": 1699869562,
        "title": "nj / es.nj.01 - Custom field test",
        "updated_at": 1699929113
    },
    "person": {
        "email": "zhangsan@toutie.com",
        "person_id": 1999632289504,
        "person_name": "zhangsan"
    }
}' -v

3. Custom Request Body and Value Mapping

Custom request body (custom_body)

By default, the system pushes the complete JSON data following the Payload structure described above. If your receiver requires a specific data format, you can use a custom request body to reorganize the push content. Use {{field.path}} syntax to reference any field from the default Payload. The system replaces variables with actual values at push time. Variable syntax:

Use . to separate path levels, e.g. {{incident.title}} references the incident title
Array index access is supported, e.g. {{incident.responders.0.email}} references the first responder’s email
When the entire value is a single variable (e.g. "{{incident.labels}}"), the original data type is preserved (object, array, number, etc.)
When a variable is mixed with other text (e.g. "Incident: {{incident.title}}"), the variable is converted to a string for concatenation

Example:

{
  "action": "{{event_type}}",
  "incident_id": "{{incident.incident_id}}",
  "title": "{{incident.title}}",
  "severity": "{{incident.incident_severity}}",
  "url": "{{incident.detail_url}}",
  "operator": "{{person.person_name}}",
  "labels": "{{incident.labels}}"
}

If a variable path does not exist in the default Payload, the system keeps the original {{...}} text without replacement. It is recommended to first check the actual default Payload via a test push to confirm available field paths.

Value mapping (value_mapping)

Value mapping automatically transforms field values during variable resolution in the custom request body. Value mapping is configured per field path. Example:

{
  "incident.incident_severity": {
    "Critical": "P0",
    "Warning": "P1",
    "Info": "P2"
  }
}

Used with "severity": "{{incident.incident_severity}}" in the custom request body, when the incident severity is Critical, the severity field in the push result will be P0. Values that do not match any mapping are sent as-is.

4. Use Cases

Restart Host

When host memory or CPU is maxed out, trigger a host restart script to quickly complete the restart.

Information Enrichment

When an incident occurs, callback to your service to retrieve Tracing, Logging, topology and other information based on alert details, then proactively call Flashduty Open API to update incident information, such as adding labels or setting custom fields, to assist troubleshooting.

Rollback Changes

When an incident occurs, if it’s determined to be caused by a change, directly trigger a callback to your deployment platform to start the rollback process and accelerate incident recovery.

Update Status Page

When an incident is confirmed to impact production services, trigger external status page updates to promptly notify your customers or upstream/downstream parties.

5. FAQ

Is there a response timeout?
- Service needs to return response within 1 second; exceeding 1 second is considered a failure
Will pushes continue after failure?

Retries for specific network errors, max 1 retries:

context deadline exceeded (excluding awaiting headers)
i/o timeout
eof

Trusted IP whitelist for push source?
- May be updated in the future, please check regularly

Quick Start

Channels

Incident Management

Post-Mortem

Status Page

Analytics

Integration Settings

Configuration

Advanced

Integrations

Best Practices

1. Create Action

2. Push Description

Request Method

Request Payload:

Request Response

Request Example

3. Custom Request Body and Value Mapping

Custom request body (custom_body)

Value mapping (value_mapping)

4. Use Cases

Restart Host

Information Enrichment

Rollback Changes

Update Status Page

5. FAQ

​1. Create Action

​2. Push Description

​Request Method

​Request Payload:

​Request Response

​Request Example

​3. Custom Request Body and Value Mapping

​Custom request body (custom_body)

​Value mapping (value_mapping)

​4. Use Cases

​Restart Host

​Information Enrichment

​Rollback Changes

​Update Status Page

​5. FAQ

1. Create Action

2. Push Description

Request Method

Request Payload:

Request Response

Request Example

3. Custom Request Body and Value Mapping

Custom request body (custom_body)

Value mapping (value_mapping)

4. Use Cases

Restart Host

Information Enrichment

Rollback Changes

Update Status Page

5. FAQ