Fortinet Document Library

Version:


Table of Contents

User Guide

21.4.0
Copy Link

Webhooks

The Webhook Notification integration allows you to receive an HTTP request whenever your servers experience an outage or return from an outage. If you have multiple outages at the same time, you will receive a separate HTTP request per outage, as opposed to them being grouped together, like they are in other notification types.

All webhook requests originate from the following IP addresses:

  • 104.197.35.194/32

  • 35.185.29.9/32

Configure your firewall to allow inbound webhook traffic. Note that these IP addresses are subject to change and you will be notified prior to any such change.

The Postback can be set up via the Integrations page, which is found under the Settings menu item.

Configuration

  1. Go to Settings > Integrations.

  2. Locate the Webhook card then click Configure.

  3. Configure the following fields:

Field

Description

Title 

Enter a title for the Webhook. This title will be referred to in the Alert Timelines.

Trigger Event

Select the type of event that will trigger the payload.

Request Method

Alerts can be sent via HTTP POST, PUT, DELETE, or GET operations, choose whichever your system is set up to receive.

Postback URL

The URL you wish to send the alert to.

HTTP Headers

If you need HTTP headers, select Add New Header.

Authentication Method

Select None or Basic. If you select basic, enter your credentials in the HTTP Auth Username and HTTP Auth Password fields.

Payload Type

Select Raw Payload or Form Variables.

If you select Form Variables, you can directly input the variable's name and value. The values can be set up to include macros that expand to the actual details of the outage, for example including $fqdn in a value will get replaced with the actual domain name of the outage. Details on all of the parameters are shown on the right side of the form.  For more information, see Raw payload example.

4. Select Save.

To add another Webhook event, select Add Event then repeat steps 3 and 4.

The webhook functionality is quite useful for integrating monitoring results into the rest of your infrastructure. Some of the uses that we have seen so far are:

  • Automatically open tickets in your ticketing system when an outage begins.

  • Display alerts for currently down servers in an internal company dashboard/panic board.

  • Pipe messages into internal chat systems (although we now support sending alerts directly to Google Chat and IRC chat rooms as well).

If you have other interesting integrations that you set up with this, we'd love to hear about them. Also, if you find that the webhook functionality is missing something that is preventing you from using it, please let us know about that too so we can see if it can be extended.

Raw payload example

Incident Detection webhook 

{
"cards": [
{
"header": {
"title": "Panopta - $trigger",
"imageUrl": "https://www.panopta.com/wp-content/uploads/2017/01/Favicon.png"
},
"sections": [
{
"widgets": [
{
"keyValue": {
"topLabel": "Severity",
"content": "$severity"
}
},
{
"keyValue": {
"topLabel": "Instance",
"content": "<a href='https://my.panopta.com/report/InstanceDetails?server_id=$server_id#panel_1'>$name</a>"
}
},
{
"keyValue": {
"topLabel": "Start Time",
"content": "$timestamp"
}
},
{
"keyValue": {
"topLabel": "Impacted Metric(s)",
"content": "$items"
}
}
]
},
{
"widgets": [
{
"buttons": [
{
"textButton": {
"text": "View in Panopta",
"onClick": {
"openLink": {
"url": "https://my.panopta.com/outage/IncidentDetails?incident_id=$outage_id#panel_1"
}
}
}
}
]
}
]
}
]
}
]
}

Parameters

Parameter

Description

$trigger

The type of event that triggered this payload (outage, ack, broadcast, clear)

$fqdn

The Fully qualified domain name of the server experiencing the incident/clear.

$name

Name of the server experiencing the incident/clear.

$timestamp

UTC timestamp of when the incident/clear occurred.

$event

The type of event, either incident event or clear event.

$outage_id

The ID number of the associated incident.

$services 

For service incident: services experiencing the incident/clear.

$compound_service_id

The ID number of the compound metric affected.

$network_service_id 

The ID number of the network service affected.

$resource

For resource anomalies: resources experiencing the anomaly/clear.

$server_resource_id 

The ID number corresponding to the resource affected.

$items 

Services experiencing the incident/clear or resources experiencing the anomaly/clear.

$reasons 

The reasons for network service incidents or the details for anomalies.

$duration

The duration of incidents/anomalies which will be filled in on-clear.

$tags

The tags for the server.

$server_key 

The server key for the server.

$server_id

The ID number of the server experiencing the incident/clear.

$partner_server_id 

The partner server id for the server.

$item_type

The service type textkeys of the services experiencing the incident/clear, or plugin_textkey/resource_textkey combinations of the resources the experiencing the anomaly/clear, or the OID name of SNMP resources experiencing the outage/clear.

$custom_attribute 

You can pass custom server attributes that are set on your servers. Use the attribute type as the key.

$alert_label

Alert label of the incident/anomaly.

$severity 

The severity of the outage/anomaly, either critical or warning.

$metric_tags

The tags for all of the metrics involved in the outage.

$location

A comma-separated list of the primary monitoring probe names for all network services affected.

$message 

For ack and broadcast payloads, the message that was sent.

$incident_lead 

The incident lead's email address, if set.

$alert_timeline 

The name of the alert timeline used for the incident.

$alert_timeline_id

The ID of the alert timeline used for the incident.

Webhooks

The Webhook Notification integration allows you to receive an HTTP request whenever your servers experience an outage or return from an outage. If you have multiple outages at the same time, you will receive a separate HTTP request per outage, as opposed to them being grouped together, like they are in other notification types.

All webhook requests originate from the following IP addresses:

  • 104.197.35.194/32

  • 35.185.29.9/32

Configure your firewall to allow inbound webhook traffic. Note that these IP addresses are subject to change and you will be notified prior to any such change.

The Postback can be set up via the Integrations page, which is found under the Settings menu item.

Configuration

  1. Go to Settings > Integrations.

  2. Locate the Webhook card then click Configure.

  3. Configure the following fields:

Field

Description

Title 

Enter a title for the Webhook. This title will be referred to in the Alert Timelines.

Trigger Event

Select the type of event that will trigger the payload.

Request Method

Alerts can be sent via HTTP POST, PUT, DELETE, or GET operations, choose whichever your system is set up to receive.

Postback URL

The URL you wish to send the alert to.

HTTP Headers

If you need HTTP headers, select Add New Header.

Authentication Method

Select None or Basic. If you select basic, enter your credentials in the HTTP Auth Username and HTTP Auth Password fields.

Payload Type

Select Raw Payload or Form Variables.

If you select Form Variables, you can directly input the variable's name and value. The values can be set up to include macros that expand to the actual details of the outage, for example including $fqdn in a value will get replaced with the actual domain name of the outage. Details on all of the parameters are shown on the right side of the form.  For more information, see Raw payload example.

4. Select Save.

To add another Webhook event, select Add Event then repeat steps 3 and 4.

The webhook functionality is quite useful for integrating monitoring results into the rest of your infrastructure. Some of the uses that we have seen so far are:

  • Automatically open tickets in your ticketing system when an outage begins.

  • Display alerts for currently down servers in an internal company dashboard/panic board.

  • Pipe messages into internal chat systems (although we now support sending alerts directly to Google Chat and IRC chat rooms as well).

If you have other interesting integrations that you set up with this, we'd love to hear about them. Also, if you find that the webhook functionality is missing something that is preventing you from using it, please let us know about that too so we can see if it can be extended.

Raw payload example

Incident Detection webhook 

{
"cards": [
{
"header": {
"title": "Panopta - $trigger",
"imageUrl": "https://www.panopta.com/wp-content/uploads/2017/01/Favicon.png"
},
"sections": [
{
"widgets": [
{
"keyValue": {
"topLabel": "Severity",
"content": "$severity"
}
},
{
"keyValue": {
"topLabel": "Instance",
"content": "<a href='https://my.panopta.com/report/InstanceDetails?server_id=$server_id#panel_1'>$name</a>"
}
},
{
"keyValue": {
"topLabel": "Start Time",
"content": "$timestamp"
}
},
{
"keyValue": {
"topLabel": "Impacted Metric(s)",
"content": "$items"
}
}
]
},
{
"widgets": [
{
"buttons": [
{
"textButton": {
"text": "View in Panopta",
"onClick": {
"openLink": {
"url": "https://my.panopta.com/outage/IncidentDetails?incident_id=$outage_id#panel_1"
}
}
}
}
]
}
]
}
]
}
]
}

Parameters

Parameter

Description

$trigger

The type of event that triggered this payload (outage, ack, broadcast, clear)

$fqdn

The Fully qualified domain name of the server experiencing the incident/clear.

$name

Name of the server experiencing the incident/clear.

$timestamp

UTC timestamp of when the incident/clear occurred.

$event

The type of event, either incident event or clear event.

$outage_id

The ID number of the associated incident.

$services 

For service incident: services experiencing the incident/clear.

$compound_service_id

The ID number of the compound metric affected.

$network_service_id 

The ID number of the network service affected.

$resource

For resource anomalies: resources experiencing the anomaly/clear.

$server_resource_id 

The ID number corresponding to the resource affected.

$items 

Services experiencing the incident/clear or resources experiencing the anomaly/clear.

$reasons 

The reasons for network service incidents or the details for anomalies.

$duration

The duration of incidents/anomalies which will be filled in on-clear.

$tags

The tags for the server.

$server_key 

The server key for the server.

$server_id

The ID number of the server experiencing the incident/clear.

$partner_server_id 

The partner server id for the server.

$item_type

The service type textkeys of the services experiencing the incident/clear, or plugin_textkey/resource_textkey combinations of the resources the experiencing the anomaly/clear, or the OID name of SNMP resources experiencing the outage/clear.

$custom_attribute 

You can pass custom server attributes that are set on your servers. Use the attribute type as the key.

$alert_label

Alert label of the incident/anomaly.

$severity 

The severity of the outage/anomaly, either critical or warning.

$metric_tags

The tags for all of the metrics involved in the outage.

$location

A comma-separated list of the primary monitoring probe names for all network services affected.

$message 

For ack and broadcast payloads, the message that was sent.

$incident_lead 

The incident lead's email address, if set.

$alert_timeline 

The name of the alert timeline used for the incident.

$alert_timeline_id

The ID of the alert timeline used for the incident.