Sysdig Documentation

Configure a Webhook Channel

Sysdig Monitor and Sysdig Secure support sending an alert notification to a destination (a website, custom application, etc.) for which Sysdig does not have a native integration. Do this using a custom webhook channel.

Prerequisites

  • Webhooks via HTTPS only work if a signed/valid certificate is in use.

  • Have your desired destination URL on hand.

Enable Feature in the UI

  1. Complete steps 1-3 in Set Up a Notification Channel and choose Webhook.

    373575663.png
  2. Enter the webhook channel configuration options:

    URL: The destination URL to which notifications will be sent Channel Name: Add a meaningful name, such as "Ansible," "Webhook.Site," etc.

    Enabled: Toggle on/off Notification options: Toggle for notifications when alerts are resolved and/or acknowledged.

    Test notification: Toggle to be notified that the configured URL is working.

  3. Click Save.

When the channel is created, you can use it on any alerts you create.

Then, when the alert fires, the notification will be sent as a POST in JSON format to your webhook endpoint. (See Alert Output, below.)

For testing purposes, you can use a third-party site to create a temporary endpoint to see exactly what a Sysdig alert will send in any specific notification.

Option: Configure Custom Headers or Data

By default, alert notifications follow a standard format (see Description of POST Data, below).

However, some integrations require additional headers and/or data, which you can append to the alert format using a custom header or custom data entry.

For example, Ansible uses token-based authentication, which requires an entry for the bearer token. This entry is not included in the default alert template built into Sysdig, but you can add it using a custom header.

You must do this from the command line, as described below.

Note

  • additionalHeaders is usually used for authentication

  • customData is used to add values to the alert

Sample Use Case

This example adds two custom headers and defines additional custom data, as well as the format for that data.

  1. Use the curl command to retrieve all configured notification channels:

    curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'Authorization: Bearer API-KEY'
  2. Add the custom headers and execute the request:

    curl -X PUT https://app.sysdigcloud.com/api/notificationChannels/1 -H 'Authorization: Bearer API-KEY' -H 'Content-Type: application/json' -d '{
      "notificationChannel": {
        "id": 1,
        "version": 1,
        "type": "WEBHOOK",
        "enabled": true,
        "name": "Test-Sysdig",
        "options": {
          "notifyOnOk": true,
          "url": "https://hookb.in/v95r78No",
          "notifyOnResolve": true,
          "customData": {
            "String-key": "String-value",
            "Double-key": 2.3,
            "Int-key": 23,
            "Null-key": null,
            "Boolean-key": true
          },
          "additionalHeaders": {
            "Header-1": "Header-Value-1",
            "Header-2": "Header-Value-2"
          }
        }
      }
    }'

Standard Alert Output

Alerts that use a custom webhook for notification send a JSON-format with the following data.

Description of POST Data:

"timestamp": Unix timestamp of when notification fired
"timespan": alert duration in seconds
"alert": info on the alert that generated the event triggering the notification
    "severity": 0 - 7 int value
    "editUrl": URL to edit the alert
    "scope": scope as defined in the alert
    "name": alert name
    "description": alert description
    "id": alert id
"event": info on the event that triggered the notification
    "id": event id
    "url": URL to view the event
"state": ACTIVE (alert condition is met) or OK (alert condition no longer met)
"resolved": false (alert has not been manually resolved) or true (it has)
"entities": array of nodes within the alert scope that triggered the notification
    "entity": metadata to identify the node
    "metricValues": array of metrics that triggered the notification
          "metric": metric name
          "aggregation": time aggregation method used to calculate the metric
          "groupAggregation": group aggregation method used to calculate the metric
          "value": metric value
    "additionalInfo": array of additional metadata about the entity
          "metric": metadata key
          "value": metadata value
"condition": alert condition

Example of POST Data:

{
 "timestamp": 1471457820000000,
 "timespan": 60000000,
 "alert": {
   "severity": 4,
   "editUrl": "http://app.sysdigcloud.com/#/alerting/alerts/1/edit",
   "scope": "host.mac = \"00:0c:29:04:07:c1\"",
   "name": "alertName",
   "description": "alertDescription",
   "id": 1
 },
 "event": {
   "id": 1,
   "url": "http://app.sysdigcloud.com/#/alerting/notifications/l:604800/1/details"
 },
 "state": "ACTIVE",
 "resolved": false,
 "entities": [{
   "entity": "host.mac = '00:0c:29:04:07:c1'",
   "metricValues": [{
     "metric": "cpu.used.percent",
     "aggregation": "timeAvg",
     "groupAggregation": "none",
     "value": 100.0
   }],
   "additionalInfo": [{
     "metric": "host.hostName",
     "value": "sergio-virtual-machine"
   }]
 }],
 "condition": "timeAvg(cpu.used.percent) > 10"
}

Example of Failure

$ curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'authorization: Bearer dc1a42cc-2a5a-4661-b4d9-4ba835fxxxxx’'

{"timestamp":1543419336542,"status":401,"error":"Unauthorized","message":"Bad credentials","path":"/api/notificationChannels"}

Example of Success

$ curl -X GET https://app.sysdigcloud.com/api/notificationChannels -H 'Authorization: Bearer dc1a42cc-2a5a-4661-b4d9-4ba835fxxxxx'
{"notificationChannels":[{"id":18968,"version":2,"createdOn":1543418691000,"modifiedOn":1543419020000,"type":"WEBHOOK","enabled":true,"sendTestNotification":false,"name":"robin-webhook-test","options":{"notifyOnOk":true,"url":"https://postb.in/6dtwzz7l","notifyOnResolve":true}}]}
$

The webhook feature is used to integrate the following channels: