Notifications Webhook

The Notifications Webhook lets you share incidents with another application or service programmatically via a callback URL.

Key Features

  • Enables custom integrations by sending high-level, correlated incidents from BigPanda to any Webhook receiver you configure.

  • Sends incident data to an external URL via HTTP POST request.

  • Supports custom authentication headers for data security.

  • Supports AutoSharing, manual sharing, and sharing updates.

Webhooks Explained

In general, Webhooks are a programmatic way to send information to an Internet address when an event occurs in an application. In BigPanda, the Notifications Webhook allows you to send incident information to a callback URL when an incident is shared and when the shared incident is updated.

Configure webhooks to build custom integrations with messaging, ticketing, or other collaboration systems.

How It Works

A Notifications Webhook integration creates a sharing channel from BigPanda to a callback URL of your choosing. When an incident is shared via the channel, BigPanda sends an HTTP POST request to the callback URL. The data payload of the request is the Incident object with the expanded representation of the Alertobjects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for new shares from BigPanda. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to create a ticket for the team that handles incident escalations.

If a change occurs that triggers a sharing update for the incident, BigPanda sends another HTTP POST request to the callback URL, with the updated Incidentobject and Alert objects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for updates to existing BigPanda shares. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to update the existing ticket for the shared incident.

You can use the Notifications webhook to build any number of custom collaboration integrations. As with other sharing channels, the same incident update can be shared through multiple webhook integrations.

Common Use Cases

The Notifications webhook is often used to integrate BigPanda with messaging, ticketing, or other collaboration systems. Some systems provide built-in API endpoints and scripting layers for receiving and transforming data according to custom business logic. Alternatively, you can build a custom API endpoint within your infrastructure or by using cloud services such as Amazon API Gateway and AWS Lambda.

Integrating Collaboration Systems With The Notifications Webhook

To build a custom integration with the Notifications webhook, you must configure the collaboration system to receive and use BigPanda incident data. Then, configure BigPanda to send the data.
Follow this general process to use the Notifications Webhook:

  1. Configure The API Endpoint To Receive The Webhook.
    Be sure to configure security settings for authenticating requests, such as API keys or user account credentials. Consider configuring responses with status codes to aid in testing and troubleshooting.

  2. Set Up The Receiving System To Use The Data.
    Apply custom business logic, transform the data, and/or perform actions in the system with custom code or settings. As necessary, configure data storage, include logic for receiving multiple requests about the same incident, and/or configure the API endpoint to trigger any custom code when data is received.

  3. Configure The Webhook Settings In BigPanda.
    Create a sharing channel from BigPanda to the application or service. Provide the callback URL and authentication headers that BigPanda will use to send the incident data.

  4. Test The Webhook.

  5. Configure Environments And AutoShare Rules To Use The Webhook Sharing Channel, As Necessary.

👍

You can use the Incidents API to build a bidirectional integration with a collaboration system.

For example, if you are building a webhook integration that creates a ticket in a service desk application, you may want to use the Incidents API to automatically resolve the BigPanda incident when the service desk ticket is closed.

To learn more about installing Notification Webhooks in BigPanda, see the instructions in BigPanda, or in the Webhooks Installation Instructions.

Notification Webhook Object

Defines the schema for incident information that is sent in a BigPanda webhook share

Parameters

The Incident object schema includes the following attributes:

Parameter

Description

Type

Example

id

System-generated unique identifier for the incident.

String

"id": "1555a53b6789c12d3efg45h"

status

Current incident status, which is determined by the most severe status of the correlated alerts. Possible statuses: [critical, warning, unknown, ok].

String

"status" : "critical"

active

Whether the incident contains at least one active alert and has not been manually resolved. An incident is automatically resolved when all the alerts are resolved.

Boolean

"active": true

severity

The highest status reached by any alert in the incident at any time

String

“severity”: “critical”

flapping

Signifies whether at least one correlated alert has changed states frequently enough to be treated as flapping

Boolean

"flapping": false

snooze

Snooze options for the incident

Attributes:
snoozed - Whether the incident is currently snoozed.

end_time - Time when the current snooze period expires, in Unix epochs.

autoCancel - Whether the current snooze should be automatically cancelled if a new alert is added, the severity of an existing alert increases, or the incident is resolved and then reopens.

Object

"snooze" : {"snoozed" : false, "end_time" : null, "autoCancel" : false}

startedOn

Time when the earliest correlated alert was received, in Unix epochs.

Timestamp (in seconds)

"startedOn": 1466416853

changedOn

Time of the last change to the incident that triggered applicable sharing updates, in Unix epochs.

Timestamp (in seconds)

"changed_at": 1466417169

updatedOn

Time of last change to incident, in Unix epochs.

Timestamp (in seconds)

"updated_at": 1466417169

endedOn

Time when the incident status was set to ok, in Unix epochs.

Timestamp (in seconds)

"end": null

alerts

Array of the alert objects correlated into the incident.

Attributes:
id - System-generated unique identifier for the alert.

status - The most severe status the alert triggered
Possible returns are: [critical, warning, unknown, ok]

startedOn - Unix time when the initial alert started

endedOn - Unix time when the alert was resolved

changedOn - Unix time when the alert status last changed

updatedOn - Unix time of last change to the alert

active - Whether the alert is active and has not been manually resolved.

primaryProperty - Main object that triggered the alert

secondaryProperty - Secondary object or sub-item that triggered the alert

sourceSystem - Integrated monitoring system that sent the alert to BigPanda

description - Brief summary (max. 2048 characters) of the alert included by certain monitoring tools

tags - Array of name-value pairs that represent alert properties. Each object includes: name and value of each tag

Array of Objects

[ {
"id": "5555370aabc20a001145c5e9",
"status": "Critical",
"startedOn": 1649576282,
"endedOn": null,
"changedOn": 1649576282,
"updatedOn": 1649576282,
"active": true,
"primaryProperty": "host",
"secondaryProperty": "check",
"sourceSystem": "nagios.est",
"description": "CPU is 98%",
"tags": [
{
"name": "check",
"value": "CPU"
} ]

links

The url where the incident preview can be accessed

String

"links": {
"landingPage": "http://bigp.io/9ad55554d5c116e4"
}

incidentTags

An array of Incident tags associated with the incident

Attributes:
id - unique identifier for the tag

value - value of the incident tag according to its type

Array of Objects

"incidentTags": [
{
"id": "itd_priority_1",
"value": 1000
}
]

metadata

Information on the share action itself

Attributes:
sender - object with name and email of the user who initiated the share. Autoshares will list BigPanda as the sender.

environment - name of the environment in BigPanda where the incident was shared from

environment_id - system ID of the environment in BigPanda where the incident was shared from

Object

"metadata": {
"sender": {
"name": "Engineer",
"email": "[email protected]"
},
"environment": "All",
"environment_id": "55550bc8c481fd1100abc398"
}

Sample Webhook Payloads:

{
  "incident": {
    "id": "5555370aabc20a001145d6g9",
    "status": "Critical",
    "active": true,
    "severity": "Critical",
    "flapping": false,
    "resolved": false,
    "snooze": {
      "snoozed": false,
      "wake": null,
      "autoCancel": false
    },
    "startedOn": 1649576282,
    "changedOn": 1649576282,
    "updatedOn": 1652897578,
    "endedOn": null,
    "alerts": [
      {
        "id": "5555370aabc20a001145c5e9",
        "status": "Critical",
        "startedOn": 1649576282,
        "endedOn": null,
        "changedOn": 1649576282,
        "updatedOn": 1649576282,
        "active": true,
        "primaryProperty": "host",
        "secondaryProperty": "check",
        "sourceSystem": "nagios.est",
        "description": "CPU is 98%",
        "tags": [
          {
            "name": "check",
            "value": "CPU"
          },
          {
            "name": "_cluster",
            "value": "modiin-prod"
          },
          {
            "name": "run-book",
            "value": "https://mywiki.com/Evyatar-11/modiin-prod"
          },
          {
            "name": "host",
            "value": "Evyatar-11"
          }
        ]
      },
      {
        "id": "555537133ec0020012c96a28",
        "status": "Critical",
        "startedOn": 1649576282,
        "endedOn": null,
        "changedOn": 1649576282,
        "updatedOn": 1649576282,
        "active": true,
        "primaryProperty": "host",
        "secondaryProperty": "check",
        "sourceSystem": "nagios.est",
        "description": "CPU is 98%",
        "tags": [
          {
            "name": "check",
            "value": "CPU"
          },
          {
            "name": "host",
            "value": "web3"
          },
          {
            "name": "_cluster",
            "value": "modiin-prod"
          },
          {
            "name": "run-book",
            "value": "https://mywiki.com/web3/modiin-prod"
          }
        ]
      }
    ]
  },
  "links": {
    "landingPage": "http://bigp.io/9ad55554d5c116e4"
  },
  "incidentTags": [
    {
      "id": "itd_priority_1",
      "value": 1000
    }
  ],
  "metadata": {
    "sender": {
      "name": "Engineer",
      "email": "[email protected]"
    },
    "environment": "All",
    "environment_id": "55550bc8c481fd1100abc398"
  }
}

{
  "incident": {
    "id": "65552cca4096630011027754",
    "status": "Critical",
    "active": true,
    "severity": "Critical",
    "flapping": false,
    "resolved": false,
    "snooze": {
      "snoozed": false,
      "wake": null,
      "autoCancel": false
    },
    "startedOn": 1651780810,
    "changedOn": 1651780810,
    "updatedOn": 1653608416,
    "endedOn": null,
    "alerts": [
      {
        "id": "65552cca4096630011027754",
        "status": "Critical",
        "startedOn": 1651780810,
        "endedOn": null,
        "changedOn": 1651780810,
        "updatedOn": 1651780810,
        "active": true,
        "primaryProperty": "host",
        "secondaryProperty": "check",
        "sourceSystem": "nagios1",
        "description": null,
        "tags": [
          {
            "name": "environment",
            "value": "environment_1"
          },
          {
            "name": "up_stream_services",
            "value": [
              "Database 2",
              "API Server 2",
              "App Server 2",
              "Switch 3"
            ]
          }
            ]
          },
          {
            "name": "location",
            "value": "location_1"
          },
          {
            "name": "application",
            "value": "application_1"
          },
          {
            "name": "check",
            "value": "check_5"
          },
          {
            "name": "host",
            "value": "host_2"
          }
        ]
      },
      {
        "id": "55542cca4096630011027753",
        "status": "Critical",
        "startedOn": 1651780810,
        "endedOn": null,
        "changedOn": 1651780810,
        "updatedOn": 1651780810,
        "active": true,
        "primaryProperty": "host",
        "secondaryProperty": "check",
        "sourceSystem": "datadog",
        "description": null,
        "tags": [
          {
            "name": "environment",
            "value": "environment_1"
          },
          {
            "name": "host",
            "value": "host_1"
          },
          {
            "name": "down_stream_services",
            "value": [
              "CSL - COMMON SERVICES LAYER",
              "CSL - EXPANSION",
              "EMPLOYEEJA"
            ]
          },
          {
            "name": "location",
            "value": "location_1"
          },
          {
            "name": "application",
            "value": "application_1"
          },
          {
            "name": "check",
            "value": "check_5"
          },
          {
            "name": "runbook",
            "value": "ftp://runbook.running/"
          }
        ]
      }
    ]
  },
  "links": {
    "landingPage": "http://bigp.io/555d66fffb9d26f9"
  },
  "incidentTags": [
    {
      "id": "itd_priority_1",
      "value": 997
    },
    {
      "id": "runbook_url",
      "value": "ftp://runbook.running/"
    }
  ],
  "metadata": {
    "sender": {
      "name": "Carlos Chen",
      "email": "[email protected]"
    },
    "environment": "All",
    "environment_id": "5b55549671033c2631126aee",
    "message": "Sharing for visibility"
  }
}