> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom actions
**Plan requirement**: This feature requires an On-call Standard or higher subscription. [Learn more](https://flashcat.cloud/flashduty/price/)
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
1. Login to Flashduty console, go to **Integration Center - Webhook**
2. Click to add Custom Action integration
3. Configure Action Name—this name will appear as a button in incident details
4. Configure Managing Team—select the team that manages this integration; only team members can edit the integration configuration
5. Configure Channels—you can configure multiple, but each channel can have at most **5** Custom Actions
6. Configure Endpoint and custom Headers
7. **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.
7. 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](#Person) | No | Operator, only exists for human actions |
| incident | [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](#Person) | No | Creator info, only exists for manually created incidents |
| closer | [Person](#Person) | No | Closer info, only exists for manually closed incidents |
| responders | \[][Responder](#Responder) | No | Responders list |
| alerts | [Alert](#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](#request-payload) 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:**
```json theme={null}
{
"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:**
```json theme={null}
{
"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
1. **Is there a response timeout?**
* Service needs to return response within 1 second; exceeding 1 second is considered a failure
2. **Will pushes continue after failure?**
Retries for specific network errors, max 1 retries:
* context deadline exceeded (excluding awaiting headers)
* i/o timeout
* eof
3. **Trusted IP whitelist for push source?**
* {ip_whitelist}
* May be updated in the future, please check regularly