> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Incident webhook
Configure incident Webhook. When specific operations occur on incidents (such as trigger or close), the system makes an HTTP callback to your configured address. The callback content includes the incident's latest key information, allowing integration with your custom tools.
## 1. Event Types
The following event types are currently supported; more may be added in the future.
| Event Type | Description |
| :------------: | :------------------------------- |
| i\_new | Create incident (auto or manual) |
| i\_assign | Assign incident (auto or manual) |
| i\_a\_rspd | Add responders |
| i\_snooze | Manually snooze incident |
| i\_wake | Cancel snooze |
| i\_ack | Manually acknowledge incident |
| i\_unack | Cancel acknowledgment |
| i\_storm | Trigger storm warning |
| i\_custom | Trigger custom action |
| i\_rslv | Close incident (auto or manual) |
| i\_reopen | Reopen incident |
| i\_merge | Manually merge incident |
| i\_comm | Add comment |
| i\_r\_title | Update incident title |
| i\_r\_desc | Update incident description |
| i\_r\_impact | Update incident impact |
| i\_r\_rc | Update incident root cause |
| i\_r\_rsltn | Update incident resolution |
| i\_r\_severity | Update incident severity |
| i\_r\_field | Update incident custom field |
## 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, enum values see [Event Types](#EventTypes) |
| 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, only exists after incident is assigned. May be empty for i\_new event |
| 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. `56E25B`). 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 |
### Request Response
HTTP status code 200 indicates successful push.
### Request Example
```
curl -X POST 'https://example.com/incident/webhook?a=a' \
-H 'Content-Type: application/json' \
-H 'X-Customize-Header-A: a' \
-d '{
"event_id":"fac0599a2a25529ba2362c0c184b6cfb",
"event_time":1689335086948,
"event_type":"i_new",
"incident":{
"account_id":74058170041504,
"account_name":"TouTie Tech",
"ack_time":0,
"alert_cnt":0,
"assigned_to":{
"assigned_at":1689335086,
"escalate_rule_id":"64abb8a687e7984845822139",
"escalate_rule_name":"Default Escalation",
"id":"NBRbNwDSTSMijKXdLtBU3T",
"layer_idx":0,
"type":"assign"
},
"channel_id":1840312623504,
"channel_name":"Reduce Noise",
"close_time":0,
"created_at":1689335086,
"creator":{
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"TouTie"
},
"creator_id":1552048792504,
"data_source_id":0,
"dedup_key":"",
"description":"",
"detail_url":"http://10.206.0.17:8567/incident/detail/64b1352e376e32c85c56e25b",
"end_time":0,
"equals_md5":"",
"group_method":"n",
"impact":"",
"incident_id":"64b1352e376e32c85c56e25b",
"incident_severity":"Critical",
"incident_status":"Critical",
"labels":{
"check": "cpu idle low"
},
"last_time":1689335086,
"num":"56E25B",
"progress":"Triggered",
"resolution":"",
"responder_ids":[
1552048792504
],
"responders":[
{
"acknowledged_at":0,
"assigned_at":1689335086,
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"TouTie"
}
],
"root_cause":"",
"snoozed_before":0,
"start_time":1689335086,
"title":"ysy028",
"updated_at":1689335086
},
"person":{
"email":"toutie@flashcat.cloud",
"person_id":1552048792504,
"person_name":"TouTie"
}
}' -v
```
## 3. Configuration Guide
Go to **Integration Center** → **Webhook** → Add or edit an **Incident Webhook** integration.
### Basic Settings
Enter the integration name and description for easy management.
### Webhook Settings
| Config Item | Description |
| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpoint** | HTTP/HTTPS address to receive callbacks, must start with `http://` or `https://` |
| **TLS Verification** | Enabled by default. When disabled, TLS certificate verification of the target server is skipped; suitable for test environments or self-signed certificates |
| **Headers** | Custom request headers in Key-Value format; multiple headers supported |
| **Channels** | Select **All Channels** or **Specific Channels**. When specific channels are selected, only incident events in those channels trigger callbacks |
| **Event Types** | Check the event types to subscribe to (see [Event Types](#EventTypes)); select all is supported. Only checked event types trigger callbacks |
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.
### Custom request 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:**
Transform the default Payload into a custom format for an internal system:
```json theme={null}
{
"msg_type": "incident",
"event": "{{event_type}}",
"content": {
"id": "{{incident.incident_id}}",
"name": "{{incident.title}}",
"severity": "{{incident.incident_severity}}",
"status": "{{incident.progress}}",
"channel": "{{incident.channel_name}}",
"url": "{{incident.detail_url}}",
"labels": "{{incident.labels}}",
"responders": "{{incident.responders}}"
}
}
```
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 invocation history to confirm available field paths.
### Value mapping (value\_mapping)
In the custom request body, you may need to convert Flashduty field values to the format expected by the receiving system. **Value mapping** automatically transforms values during variable resolution.
Value mapping is configured per **field path**, with each path containing a `source value → target value` mapping table.
**Example:**
Convert severity and progress to custom values for the receiving system:
```json theme={null}
{
"incident.incident_severity": {
"Critical": "P0",
"Warning": "P1",
"Info": "P2"
},
"incident.progress": {
"Triggered": "open",
"Processing": "in_progress",
"Closed": "resolved"
}
}
```
Used with the following custom request body:
```json theme={null}
{
"severity": "{{incident.incident_severity}}",
"status": "{{incident.progress}}",
"title": "{{incident.title}}"
}
```
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. Invocation History
Incident Webhook provides a complete invocation history, helping you troubleshoot push delivery and debug callback interfaces.
### View Invocation History
Go to the Incident Webhook integration detail page and switch to the **Invocation History** tab.
### Filtering and Search
| Filter | Description |
| :----------------- | :-------------------------------------------------------------------------------------- |
| **Time Range** | Select from last 1 hour, 6 hours, 1 day, 7 days, or custom range (up to 7 days of data) |
| **Incident ID** | Enter an incident ID for exact search |
| **Event Type** | Filter records by event type |
| **Request Status** | Filter by success or failure |
### History Record Fields
| Field | Description |
| :----------------- | :---------------------------------------------------------- |
| **Trigger Time** | Time when the event was triggered |
| **Event Type** | The triggered event type (e.g., `i_new`, `i_ack`, etc.) |
| **Incident ID** | Associated incident ID; click to jump to incident details |
| **Event ID** | Unique identifier for this callback; used for deduplication |
| **Request Status** | Success or failure, with HTTP status code |
| **Duration** | Round-trip request time |
| **Attempt Count** | Includes initial request and retries |
### View Invocation Details
Click **View Details** on a record to see the complete request and response information:
* **Request**: Includes Endpoint, Request Headers, and Request Payload
* **Response**: On success, shows Response Headers and Response Body; on failure, shows Error Message
## 5. FAQ
1. **Is there a response timeout?**
* Service needs to return response within 2 seconds; exceeding 2 seconds 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. **How to ensure push order?**
* Theoretically, events for the same incident are pushed in chronological order, but retries may cause out-of-order delivery
* Services can filter based on event\_time; if a later event has been received, earlier events can be filtered out. Each push carries the latest complete information, so occasional event loss is tolerable
4. **Trusted IP whitelist for push source?**
* {ip_whitelist}
* May be updated in the future, please check regularly