Notifications Webhook

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.

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.

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 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 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 Incident object 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.

https://files.readme.io/ceb9b50-webhookDiagram.png

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:

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.
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.
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.
Test the webhook.
Configure environments and AutoShare rules to use the webhook sharing channel, as necessary.

Incidents API

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.

Create an App Key

Create an app key in BigPanda.

Integration specific

You'll need a separate app key for each integrated system.

https://files.readme.io/9865f2f-Integrations_App_Key_Creation.jpg

App Key Configuration in BigPanda

Configure the Webhook

Configure the webhook receiver to accept BigPanda requests, if applicable. Then, use the form below to specify the callback URL and authentication details.

Enter the full Callback URL where BigPanda will send the request.
For example: https://my-api-endpoint.com/events
(Optional) To add custom a HTTP header, click the plus and add a key-value pair. For example:
- Header key: my-api-key
- Header value: XIpjpJPLRN79LIsAa9TdA3XnxS4VfESv65NqqH8G
Repeat step 2 for each additional header you want to add to the request.

Note: Please complete Step 1: Create an App Key before configuring the webhook.

Enable Callback Service

The callback service allows BigPanda to verify that an entity (ticket, page, message, etc) has been successfully created in the target system. This service is optional, but is highly recommended, as it will confirm that your integration is configured correctly and will prevent updates from being lost.

In order for the callback service to function properly, your API call must include an Authorization header with your unique API key, event type, incident id, and the app key. If you haven't already, create a BigPanda API key.

curl -request POST \
	-url https://api.bigpanda.io/resources/v2.1/outbound/callback \
	-header 'Content-Type: application/json' \
  -header 'Authorization: Bearer <User API Key>' \
  -data '{ 
    "event_type": "incident#new",
    "incident_id": "",
    "app_key": ""
  }'

Response:
{    
  "status": 200,    
  "data": {}
}

Webhook Incident Object

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.

Different objects

The Incidents V2 API and Notifications Webhook return different fields and formatting. This object page lists the fields delivered by the Notifications Webhook to external tools.

Example 1. Sample webhook object:

{
  "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
    }
  ],
  "relatedChanges": [
    {
      "suggested_by_bigpanda": true,
      "history": [
          {
              "updated_at": "2023-09-13T22:30:44.808Z",
              "comment": "The Host dev-Billing-02 has similar occurrences in both incident tag host and change tag summary",
              "match_certainty": "SUSPECT",
              "match_type": "ALGO_RCC",
              "suggested_by_bigpanda": true,
              "score": 3.194454072790294
          }
      ],
      "change": {
          "maintenance_condition": null,
          "id": "6501f5ac064d3de47a2dd3de",
          "identifier": "Mando-001",
          "source_system": "changes.changesintegration",
          "tags": {
              "team": "Network",
              "assignee": "Din Djarin",
              "ci": "i-sdf32fs2319iwa",
              "change location": "Mandalore",
              "risk impact": "Medium",
              "approval": "Approved"
          },
          "ticket_url": "https://your.url",
          "summary": "change.summary",
          "end": 1580369039,
          "start": 1540884139,
          "status": "Done"
      },
      "incident_id": "6501f5adb2eca000122c540d",
      "comment": "The Host dev-Billing-02 has similar occurrences in both incident tag host and change tag summary",
      "match_certainty": "SUSPECT",
      "match_type": "ALGO_RCC",
      "score": 3.194454072790294,
      "created_at": 1694627262,
      "updated_at": 1694645444,
      "id": "6501f5bed7972c001d228d00",
      "match_weight_value": 10
    }
  ],
  "metadata": {
    "sender": {
      "name": "Engineer",
      "email": "[email protected]"
    },
    "environment": "All",
    "environment_id": "55550bc8c481fd1100abc398"
  },
  "event_types": [
     {
       "event": "incident#new",
       "time": 1697123962
     },
     {
       "event": "incident-tag#upserted",
       "time": 1697123963
     },
     {
       "event": "incident-tag#upserted",
       "time": 1697123964
     }
   ]
}

Webhook Parameters

The Incident object schema includes the following attributes:

Parameter	Description	Type
id	System-generated unique identifier for the incident.	String
status	Current incident status, which is determined by the most severe status of the correlated alerts. Possible statuses: [`critical`, `warning`, `unknown`, `ok`].	String
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
severity	The highest status reached by any alert in the incident at any time	String
flapping	Signifies whether at least one correlated alert has changed states frequently enough to be treated as flapping.	Boolean
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
startedOn	Time when the earliest correlated alert was received, in Unix epochs.	Timestamp (in seconds)
changedOn	Time of the last change to the incident that triggered applicable sharing updates, in Unix epochs.	Timestamp (in seconds)
updatedOn	Time of last change to incident, in Unix epochs.	Timestamp (in seconds)
endedOn	Time when the incident status was set to ok, in Unix epochs.	Timestamp (in seconds)
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
links	The url where the incident preview can be accessed	String
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
relatedChanges	Schema definitions for all RCC relations Attributes: `suggested_by_bigpanda` - A boolean field to indicate if the change was suggested by BigPanda `history` - An array of objects with related_changes history metadata `change` - The change object related to the incident `incident_id` - The unique identifier of the related incident `comment` - A comment included with the action. `match_certainty` - The confidence level of the match. One of: None, Suspect, Match. `match_type` - The type of match. `score` - The relatedness score assigned to the change relation by the BigPanda algorithm. `created_at` - Unix time when the match was created. `updated_at` - Unix time of the last update. `id` - The unique identifier of the incident. `match_weight_value` - Weight of the match related to the incident.
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
event_types	Information on the different events that occurred within the scope of the incident. See the Activities Object for a full list of Incident Activities and Event Types. If your integration is not sending this information, contact BigPanda support.	Array of Objects

Dataset Options for Outbound Integrations

Additional dataset options can be enabled for outbound integration payloads by contacting BigPanda support. These are the dataset options available:

Option	Definition	Type	Default Integrations
sendComments	Sends an update that includes the comment as part of the metadata when comments are left on the incident. See example below.	Boolean	ServiceNow Jira PagerDuty
addEventTypes	Adds an array of event_types to the metadata object in an outbound share. This can be used to understand what type of update was triggered. `event_types` options are: incident-tag#removed incident-tag#upserted incident#become-flapping incident#closed incident#commented incident#new incident#reopen incident#snoozed incident#updated incident#ticket-sync (only for integrations not using auto-share delay feature) See example below.	Boolean	All integrations
forceIncidentTagUpdates	Sends an update through the share when Incident Tag values are changed.	Boolean	All integrations
addMetadata	Includes the environment name and environment ID to the metadata object in each webhook call. See the example below.	Boolean	All integrations
addIncidentTags	Includes any incident tags in the outbound payloads. See example below.	Boolean	All integrations
addAssignments	Includes any Assignee and Assigner in the outbound payloads. See example below.	Boolean	Not default for any integration
forceAllUpdates	Allows the incident to be shared even if it's resolved before the AutoShare. This is useful when incidents resolve within a few seconds, but the user still wants an AutoShare.	Boolean	Not default for any integration
forceFilterFlappingOrMuted	Suppresses flapping updates, even for integrations typically configured to send them, such as webhooks. If this toggle is on, BigPanda will wait to send updates until the system confirms the alert is no longer flapping. The default delay for this is 1 hour, but it may be different depending on your organization's flapping configuration.	Boolean	Not default for any integration
forceOneTime	Only sends the initial share to the target. Further updates are suppressed.	Boolean	Not default for any integration
quota	Contains share quota information for the integration. Attributes: `used`- The number of shares sent through the integration since it was last reset. `available`- The number of shares the integration is allowed to send before the next reset is performed. `last_reset`- The timestamp of when the`used`count was last reset to zero. `notified`- Flag indicating whether the organization has been notified that their quota was reached.	JSON	Not default for any integration

Example of `sendComments` option

"metadata": 
    { 
        "sender": { "name": "<USERS_NAME>", "email": "<USERS_EMAIL>" }, 
        "comment": 
            { 
                "comment": "Hello World", 
                "environment": "All" 
            } 
    }
```

Example of `addEventTypes` option

"event_types": [
    { 
        "event": "incident#new", 
        "time": 1674571309 
    }, 
    { 
        "event": "incident-tag#upserted", 
        "time": 1674571309 
    } 
]

Example of `addMetadata` option

"metadata": 
    { 
        "sender": { "name": "<USERS_NAME>", "email": "<USERS_EMAIL>" }, 
        "environment": "<ENVIRONMENT_NAME_THAT_PERFORMED_THE_SHARE>", 
        "environment_id": "<ENVIRONMENT_ID>" 
    }

Example of `addAssignments` option

"metadata": 
    { 
        "assignee": { 
            "email": "<USERS_EMAIL>", 
            "name": "<USERS_NAME>", 
            "userId": "<USERS_BIGPANDA_ID>", 
        }, 
        "assigner": { 
            "email": "<USERS_EMAIL>", 
            "name": "<USERS_NAME>", 
            "userId": "<USERS_BIGPANDA_ID>", 
        }, 
    }

Example of `addIncidentTags` option

incidentTags: [ 
    { 
        "id": "host", 
        "value": "production-database-01" 
    }, 
    { 
        "id": "check", 
        "value": "CPU-01" 
    }, 
    { 
        "id": "application", 
        "value":"bigpanda" 
    } 
]

In this section: