Skip to main content

Notifications Webhook v2

Customize share triggers and notification payloads when sending data from BigPanda to external tools like ticket and messaging systems. These payloads can include customized headers and URL paths for each notification and leverage dynamic variables for incident tags and metadata.

Key features

  • Customize the webhook payload that is sent to external tools.

  • Trigger shares to different URLs based on specific share triggers.

  • Use incident detail variables to create dynamic workflows and custom messages.

  • Send data in the relevant data type, such as integers or timestamps.

Customizable workflows and payloads

The Notifications Webhook v2 integration adds configuration options at all stages of the webhook, including the autoshare trigger, call headers, and payload data. It uses dynamic variables to streamline automation and enable granular workflow configurations with specific datasets and addresses for individual incident triggers.

Share workflows

Basic incident shares send the same message to a single endpoint for all incident triggers. The webhook v2 integration allows you to configure individual triggers instead so you can customize triggered share behavior.

For each trigger, you are able to configure:

  • Whether to suppress shares through this integration.

  • Subpaths to extend the base webhook URL.

  • Unique headers with dynamic variables, such as authorization values.

  • Customized JSON payloads to be sent in the body of the share.

You can customize behavior for each of the following triggers:

Available triggers

The supported triggers are:

  • default (Required)

  • incident#new

  • incident#updated

  • incident-tag#upserted

  • incident-tag#removed

  • incident#snoozed

  • incident#commented

  • incident#reopen

  • incident#become-flapping

  • incident#closed

  • manual

The configuration for the default trigger must be defined. This configuration will be used for any triggers that are not explicitly defined or disabled.

Disable a trigger to prevent messages being sent through this integration for that trigger type. This can prevent noise in downstream tools for irrelevant incident updates.

Disabling notifications

When disabling or enabling notifications for a trigger, the process does not interfere with current queued notifications. It can take up to 10 minutes for the disabling of a trigger to take effect.

Subpaths, methods, and headers

The overall webhook v2 configuration defines a base url to receive webhook messages. Individual triggers can use static values or dynamic variables to extend this URL.

For tools that restrict available call methods, the specific method can be defined per-event.

Headers can also be added to individual triggers. This allows for custom headers that reflect dynamic values attached to the specific incident.

Authorization headers can be defined explicitly for Basic and Bearer authorization types. These values will be encrypted in our database and then added to events that require authentication.

For example:

  • Add /{{incidentTags.itd_priority_1}} to route updates into a priority-based channel.

  • Include /{{incident.id}} to match the path to update the matching ID in the destination tool.

  • Add /{{incidentTag.servicenow_ticket}} to connect the updates to an existing ticket.

  • Define the method as "POST" to ensure all new ticket creations match requirements in the destination tool, while updates can be defined to only be sent as "PATCH" calls.

  • Add a header with "x-client-id" : "{{ primaryAlert.tags.host }}" to define the client id explicitly.

  • Include "authorization": "Bearer {{incidentTags.itd_applications_1}}" to automatically include this incident enrichment data with a dynamic value, encrypted and processed per event type.

The Content-type header is added by default and configured as application/json.

Custom payloads

The message body of a webhook must be a valid JSON-formatted object, but can include nested objects and all JSON-supported data types. The payload can include dynamic variables to further refine the information sent with each share.

For example:

  • Send technicians a message with {{primaryAlert.tags.host}} data to help troubleshoot an incident.

  • Include {{assignee.name}} details when sending incident action summaries to team leaders.

  • Let DevOps know the {{relatedChanges}} so that they can leverage AI suggestions in their workflow.

Dynamic variables

To improve automatic workflows and make notifications more valuable, leverage dynamic variables to autopopulate values based on data from specific incidents. Dynamic variables can be generated from both BigPanda’s standard system fields and from fields unique to your organization. (See the Dynamic Variables documentation for more details on available system fields.)

A GET call to the Dynamic Variables API will retrieve the full list of incident and alert fields that can be used as a variable within outbound messaging templates and workflows.

Variables can be added to paths, headers, and the payload body by framing the variable ID with double brackets: {{variable.name}}.

Configuring dynamic variables for Automated Incident Analysis

When including Automated Incident Analysis (AIA) dynamic variable for shares triggered on incident#new, the integration delay should be configured at 3 minutes or more. To learn how to adjust the initial share delay, see the AutoShare rule configuration.

Data type conversion

Integrations for Notifications Webhook v2 will automatically convert data from incident tag strings to the appropriate data type.

For example: the variable {{incident.start}} will be converted to a number in the payload: “start”: “{{incident.start}}” -> “start”: 1747856598.

To prevent conversion, embed the variable as part of a string: “start”: “Started at {{incident.start}}” → “start”: “Started at 1747856598" or use single quotes to escape the conversion: “start”: “'{{incident.start}}'“ → “start”: “1747856598"

Standard available fields for Webhook v2 Workflows

Dynamic variables can include alert fields, incident data, incident metadata, incident tags, and preview links.

Primary alert fields

Field

Description

Format

Feature support

primaryAlert.id

System-generated unique identifier for the alert.

String

Webhook v2, Email

primaryAlert.status

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

String

Webhook v2, Email

primaryAlert.is_active

Whether the alert is active and has not been resolved.

Boolean

Webhook v2, Email

primaryAlert.primary_property

Name of the main object that triggered the alert.

String

Webhook v2, Email

primaryAlert.secondary_property

Name of the secondary object or sub-item that triggered the alert.

String

Webhook v2, Email

primaryAlert.source_system

Integrated monitoring system(s) that sent the alert to BigPanda.

Array of strings

Webhook v2, Email

primaryAlert.incident_key

Deduplication rule for the primary alert, usually primary_secondary values.

String

Webhook v2, Email

primaryAlert.description

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

String

Webhook v2, Email

primaryAlert.primary

Value of primary property.

String

Webhook v2, Email

primaryAlert.secondary

Value of secondary property.

String

Webhook v2, Email

primaryAlert.maintenance

Whether the alert is currently suppressed through a maintenance plan.

Boolean

Webhook v2, Email

primaryAlert.tags.<tagname>

The tag value associated with the alert for a given tag.

String

Webhook v2, Email

Incident data

Field

Description

Format

Feature support

incident.id

System-generated unique identifier for the incident.

String

Webhook v2, Email

incident.status

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

String

Webhook v2, Email

incident.is_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

Webhook v2, Email

incident.severity

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

String

Webhook v2, Email

incident.flapping

Whether at least one correlated alert has changed states frequently enough to be treated as flapping.

Boolean

Webhook v2, Email

incident.updated_at

Time of last change to incident, in Unix epochs.

Timestamp (in seconds)

Webhook v2, Email

incident.last_change

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

Timestamp (in seconds)

Webhook v2, Email

incident.start

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

Timestamp (in seconds)

Webhook v2, Email

incident.end

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

Timestamp (in seconds)

Webhook v2, Email

incident.alert_table

An HTML-formatted table with the first 5 alerts correlated into the incident, sorted by timestamp. This variable should only be used in email templates.

Array of objects

Email

incident.resolved

Whether the incident has been resolved.

Boolean

Webhook v2

incident.snoozed

Whether the incident is currently snoozed.

Boolean

Webhook v2

incident.snooze_config

The settings for an incident snooze, including when the incident is scheduled to wake and whether automatic cancelling is enabled.

Object

Webhook v2

incident.alerts_array

All alerts correlated into the incident in JSON string format. This variable should only be used in webhook customization.

Array of objects

Webhook v2

Share metadata

These fields provide information on the share action itself.

Field

Description

Format

Feature support

metadata.environment_name

Name of the environment in BigPanda where the incident was shared from.

String

Webhook v2, Email

metadata.environment_id

Name of the environment group in BigPanda where the incident was shared from.

String

Webhook v2, Email

metadata.sender_name

The name of the user who initiated the share. Autoshares will list BigPanda as the sender.

String

Webhook v2, Email

metadata.sender_email

The email address of the user who initiated the share. Autoshares will list BigPanda as the sender.

String

Webhook v2, Email

metadata.event_types

Information on the different triggers that occurred within the scope of the incident being shared. (See Available Triggers for the full list of supported triggers.)

Array of strings

Webhook v2

metadata.performer_email

The email address of the account that added a comment to the incident.

String

Webhook v2

metadata.performer_name

Name of the account that added a comment to the incident.

String

Webhook v2

metadata.comment

Comments added to the incident in BigPanda.

String

Webhook v2

metadata.message

The annotation added to the share action.

String

Webhook v2

Incident tags

Field

Description

Format

Feature support

incident_tag.itd_ai_reasoning_1

Explanation of the logical path the AI traveled to suggest the root cause.

String

Email

incidentTags.<tag_id>

The value(s) of the specified incident tag as related to the incident.

Array of strings

Email

AI Processing delay

AI tags are generated at a 1-3 minute delay after initial incident processing. To include AI tags in static messages such as email, ensure the AutoShare is configured at a 3 minute delay.

Links

Field

Description

Format

Feature support

links.preview

The URL where the incident preview can be accessed.

The URL does not require BigPanda login.

String

Webhook v2, Email

links.console

A direct link to the incident in BigPanda.

This URL requires BigPanda login.

String

Webhook v2, Email

links.timeline

A direct link to the incident’s timeline view in BigPanda.

This URL requires BigPanda login

String

Webhook v2, Email

Assignee

Field

Description

Format

Feature support

assignee.name

Name of the account that was assigned the incident.

String

Webhook v2

assignee.username

The email address of the BigPanda user who was assigned the incident.

String

Webhook v2

Assigner

Field

Description

Format

Feature support

assigner.name

Name of the account that assigned the incident.

String

Webhook v2

assigner.username

The email address of the BigPanda user who assigned the incident.

String

Webhook v2

Additional fields

Field

Description

Format

Feature support

similarities

Incident data for Similar Incidents, if configured.

Attributes:

incident_id - The unique identifier of the similar incident.

overallSimilarityScore - Similarity score for the related incident.

llmGeneratedOverallSimilaritySummary - The AI-generated summary of why an incident was marked as similar.

serviceNowTicket - The similar incident ID in ServiceNow.

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

alertCount - The number of alerts corresponding to this incident.

priority - The priority tag assigned to the incident.

primary - The primary property tag for the incident.

secondary - The secondary property tag for the incident.

assignee - The user(s) assigned to the similar incident.

Array of objects

Webhook v2

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.

Array of objects

Webhook v2

Creating and updating a webhook v2 integration

The webhook v2 integration is currently API-only, so integrations can only be created and updated via the Notifications Webhook v2 API. Once the new integration is created via API, you will be able to access it via the share configuration screen for either AutoShare rules or manual shares. The webhook v2 integration will also appear on the Integrations tab with your other integrations, where it can be deactivated or deleted.

Note that if the integration is deleted, all configuration and AutoShare rules associated with the integration will also be deleted.

Complete integration ID needed

When updating a webhook v2 configuration, you will need the complete integration ID, including the parent integration (For example: snmp.la_site_east). If you don’t know your integration ID, you can find it by opening the integration details in the Integrations tab.

Service Accounts not supported

Currently the Webhook v2 API must be authenticated through a User Account, not a Service Account.

Notifications Webhook v2 API

The webhook v2 API allows you to programmatically manage the configuration for outbound webhook integrations and retrieve available dynamic fields for use in those outbound webhook integrations.

Read full details in the Notifications Webhook V2 API documentation.

Relevant permissions

Roles with the following permission can access the Notifications Webhook V2 API:

Name

Description

Integrations

View, install, and edit integrations in the Integrations Tab.

Notifications

View, add, edit, and delete AutoShare rules.

Permission access levels can be adjusted by selecting either View or Full Access. To learn more about how BigPanda's permissions work, see the Roles Management guide.

Service Accounts not supported

Currently the Webhook v2 API must be authenticated through a User Account, not a Service Account.

Sample webhook v2 configuration object

curl https://api.bigpanda.io/resources/v2.1/integrations \
  --request POST \
  --header 'Content-Type: application/json' \
  --data 
'{
    "name": "test_integration",
    "parent_system_id": "webhook_v2",
    "workflow_config": {
        "events": {
            "default": {
                "enabled": true,
                "headers": {
                    "Authorization": "Bearer {{incidentTags.itd_applications_1}}"
                },
                "body": {
                    "incident_start": "{{incident.start}}",
                    "assigner": "Assigned by {{assigner.username}}",
                    "assignee": "Assigned to {{assignee.username}}",
                    "primary_alert_host": "{{primaryAlert.tags.host}}",
                    "priority": "{{incidentTags.itd_priority_1}}",
                    "nested_values": {
                        "double_nested_values": {
                            "primary_alert_check": "'{{primaryAlert.tags.check}}'",
                            "incident_updated": "{{incident.updated_at}}"
                        }
                    }
                }
            },
            "incident#new": {
                "enabled": true,
                "path": "/incident/{{incident.id}}",
                "headers": {
                    "Authorization": "Bearer {{incidentTags.itd_applications_1}}"
                },
                "body": {
                    "incident_start": "{{incident.start}}",
                    "snooze_config": "{{incident.snooze_config}}",
                    "changes": "{{relatedChanges}}",
                    "similarities": "{{similarities}}",
                    "alerts_array": "{{incident.alerts_array}}",
                    "tags_array": "{{incidentTags.tags_array}}",
                    "event_types": "{{metadata.event_types}}",
                    "environment name": "{{metadata.environment_name}}",
                    "environment_id": "{{metadata.environment_id}}"
                }
            },
            "incident-tag#upserted": {
                "enabled": false
            }
        },

        "config": {
            "base_url": "https://webhook.site/37c633fb-d2ed-4832-abdf-217723bf350b",
		"expects_callbacks": true
        }
    }
}'

This POST would create the following webhook message:

{
  "incident_start": 1749496995,
  "snooze_config": {
    "snoozed": true,
    "wake": 1749497015,
    "autoCancel": false
  },
  "changes":[
    {
      "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
    }
  ],
  "similarities": [
    {
      "incident_id": "66743b43a0f57454fa87410f",
      "overallSimilarityScore": 86.67,
      "llmGeneratedOverallSimilaritySummary": "—",
      "serviceNowTicket": "INC0010002",
      "status": "ok",
      "alertCount": 3,
      "priority": null,
      "primary": "ntc-prod-syn648, ntc-prod-syn154, ntc-prod-syn936",
      "secondary": "synthetic failure",
      "assignee": null
    },
    {
      "incident_id": "66c1d6dd61d1b030aa9b2fd6",
      "overallSimilarityScore": 68.91,
      "llmGeneratedOverallSimilaritySummary": "—",
      "serviceNowTicket": null,
      "status": "ok",
      "alertCount": 1,
      "priority": null,
      "primary": "ntc-prod-syn821",
      "secondary": "synthetic failure",
      "assignee": null
    }
  ],
  "alerts_array": [
    {
      "id": "684734a385e11d14387cb702",
      "status": "Critical",
      "startedOn": 1749496995,
      "endedOn": null,
      "changedOn": 1749496995,
      "updatedOn": 1749496995,
      "active": true,
      "primaryProperty": "host",
      "secondaryProperty": "check",
      "sourceSystem": "api.test",
      "description": "CPU is above upper limit (70%)",
      "tags": [
        {
          "name": "host",
          "value": "production-database-1"
        },
        {
          "name": "check",
          "value": "CPU overloaded"
        },
        {
          "name": "_cluster",
          "value": "production-databases"
        },
        {
          "name": "alert_updates",
          "value": 1
        }
      ]
    }
  ],
  "tags_array": [
    {
      "id": "itd_hosts_1",
      "value": [
        "production-database-1"
      ]
    }
  ],
  "event_types": [
    {
      "event": "incident#new",
      "time": 1749497015
    }
  ],
  "environment name": "All",
  "environment_id": "68470acb219650b2723789ee"
}
In this section: