Custom incidents using API
FortiMonitor supports the creation of custom incidents using API, which provides a mechanism for your own applications to push event data to our system and leverage FortiMonitor’s alerting and dashboard functionality.
To use the API to create and close custom incidents, the Custom Incidents feature must be enabled on your account. Please contact our support team to have it enabled.
Access FortiMonitor's API library to see all of the supported API endpoints in detail.
Add a custom incident filter
Before you can start sending custom incidents using the API, you need to enable support on the server whose agent will be sending the incident data. To add a custom incident filter, see this topic.
Create a custom incident
This API request allows you to create a custom incident on any of your servers in FortiMonitor. The location response header contains the full URL of the new resource.
Endpoint
POST /server/{server_id}/custom_incident
The {server_id} is the Server ID of the instance where this custom incident will be created.
Authentication
For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.
Users sending API requests to FortiMonitor must have an API key and the proper user permissions.
To view and manage your API keys, see API keys.
Payload
{"description": null,
"metadata": null,
"plugin_textkey": null,
"resource_textkey": null,
"start_time": null
}
The attributes are described in the following table:
|
Attribute
|
Data type
|
Required |
Description |
|---|---|---|---|
|
description |
String |
✔ |
Human-readable description of the incident, which is shown in the control panel and alerts. |
|
metadata |
Dictionary |
|
(optional) Optional dictionary of key/value fields that will be added to the incident description. |
|
plugin_textkey |
String |
✔ |
Textkey which specifies the application category the incident relates to. |
|
resource_textkey |
String |
✔ |
Textkey which specifies the metric the incident relates to. |
|
start_time |
Date |
|
(optional) Start time in UTC; format: YYYY-MM-DD HH:MM:SS. If not provided, defaults to current time. |
Resolve an incident
This API request allows you to force resolution of a custom incident.
Endpoint
PUT /outage/{outage_id}/force_resolve
The {outage_id} is the Incident ID of the custom incident that you want to resolve using this endpoint.
Authentication
For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.
Users sending API requests to FortiMonitor must have an API key and the proper user permissions.
To view and manage your API keys, see API keys.
Payload
{"reason": null
}
The attributes are described in the following table:
|
Attribute |
Data type |
Required |
Description |
|---|---|---|---|
|
reason |
String |
|
(optional) The reason for ending the incident. This will be appended to the incident log. |
HTTP status code summary
The HTTP status codes is part of the response message that provides information on the status of your API request. The following table describes the HTTP status error codes in detail:
|
HTTP status code |
Reason |
|---|---|
|
200 - OK |
The API request is successful. |
|
400 - Bad Request |
The request failed, often due to a missing or misconfigured parameter. Check the response body for details on validation errors. |
|
401 - Unauthorized Access |
The API key provided is not valid. |
|
404 - Not Found |
The requested resource does not exist. |
|
405 - Method Not Allowed |
The server rejected the method for the requested resource. |
|
500 - Internal Server Error |
The API request failed due to an internal server error. |
Check the ErrorCode and ErrorMessage response headers for more information.