Change Event

title: "Change Event"
description: "Flashduty Change Event API Documentation."
date: "2024-11-20T10:00:00+08:00"
url: "https://developer-en.flashcat.cloud/en/flashduty/event-api/change-event"

Push change events from your own system to Flashcat Cloud through standard API. Most incidents are caused by changes, and the interaction between changes and alert events helps quickly locate incident causes.

Request Description

Request Method

POST, Content-Type:"application/json"

Request Parameters:

QueryString must include integration_key parameter for access control.

JsonBody parameters are as follows:

Field	Required	Type	Description
change_status	Yes	string	Change event status, enumeration values: Planned: ticket submitted, Ready: about to (or planned to) start, Processing: in progress, Canceled: canceled (or rolled back), Done: completed. Not all statuses need to be reported, selective reporting is allowed
change_key	Yes	string	Unique change key, usually the change ticket number. Used to merge different change events into one change
title	Yes	string	Change title
event_time	No	int64	Change event occurrence timestamp in "seconds", if change_status is Ready, future time can be reported; if not provided, current time will be used
description	No	string	Change description, no more than 2048 characters
link	No	string	Change ticket URL, used to jump to change details
labels	No	map	Change label collection, key is label name, value is label value. Labels are event descriptions, very important for future correlation. 1. Both label key and value are string type, case-sensitive. 2. Label key should not exceed 128 characters. 3. Maximum 50 labels. See `Label Content Reference` in Best Practices

Response

Body:

Field Name	Required	Type	Description
request_id	Yes	string	Request trace id for issue tracking
error	No	Error	Error description, returned only when an error occurs

Error:

Field Name	Optional	Type	Description
code	Yes	string	Error code
message	Yes	string	Error description

Code:

Error Code	HTTP Status	Description
InvalidParameter	400	Parameter error
InvalidContentType	400	Content-Type not supported
MethodNotAllowed	400	HTTP method not supported
Unauthorized	401	Authentication failed
AccessDenied	403	Authorization failed
RequestTooFrequently	429	Request too frequent
RouteNotFound	404	Request Method+Path not matched
ResourceNotFound	400	Account hasn't purchased resource, please proceed to billing center
InternalError	500	Internal or unknown error

Request Example

Request:

curl -X POST 'https://api.flashcat.cloud/event/push/change/standard?integration_key=$key' \
-H 'Content-Type: application/json' \
-d '{
    "change_status": "Done",
    "change_key": "CHANGE-002",
    "description": "Progress 100%",
    "title": "Double 12 Campaign",
    "labels": {
        "service": "flashcat",
        "cluster":"nj"
    },
    "link": "http://jira.flashcat.cloud/CHANGE-001"
}'

Successful response:

{
    "request_id": "0ace00116215ab4ca0ec5244b8fc54b0"
}

Failed response:

{
    "request_id": "0ace00116215abc0ba4e52449bd305b0",
    "error": {
        "code": "InvalidParameter",
        "message": "integration_key $key is not a valid one"
    }
}

Best Practices

Labels are event descriptions, you should enrich label content as much as possible, such as:

Change scope, like host, cluster
Change ownership information, like team, owner

Last modified: 2 个月前