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

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

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.

  • Include "Authorization": "Bearer {{incidentTags.itd_applications_1}}" to automatically include this incident enrichment data with a dynamic value.

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 API object 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"

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.

Notifications Webhook v2 API

The webhook v2 API allows you to programmatically manage the configuration for outbound webhook integrations.

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.

Available routes and actions

API endpoint

https://api.bigpanda.io/resources/v2.1/integrations 

https://api.bigpanda.io/resources/v2.1/integrations/<integration_id> 

Supported methods

POST, UPDATE, GET, DELETE

Using the DELETE route

The DELETE route requires the integration app-key rather than the integration ID. The app key can be retrieved by going to the Integrations tab and selecting the desired integration.

Webhook parameters

The webhook v2 configuration object schema includes the following attributes:

Attribute

Description

Type

name

User-defined name for this webhook configuration.

String

parent_system_id

The type of integration.

One of: webhook_v2

String

workflow_config

The configuration schema for the webhook integration.

Object

Workflow config parameters

The workflow_config object schema includes the following attributes:

Attribute

Description

Type

events

Notification settings for individual triggers.

Array of objects

config

Additional configuration settings.

Attributes:

base_url - The base URL to receive webhook messages from this integration. This route will be used for any triggers that do not have an additional path route defined.

expects_callbacks - Whether to enable locking on first share, preventing updates from being sent until a callback is received or 15 minutes has passed.

Object

Trigger parameters

Messages are automatically shared to the integrated tool when specific triggers happen to incidents. Each of these share triggers can have its own configuration, defined by the events object in the configuration. Trigger types are defined in the event_type field.

Each trigger object has the following properties:

Field name

Required

Description

enabled

Yes

Boolean determining if this trigger should be sent.

path

No

If present, path that will be appended to the workflow_config.config.base_url. May contain templated values.

headers

No

Headers to be used in the request. May contain templated values.

body

No

JSON Payload to send. May contain templated values.

Sample webhook v2 configuration object

Example: Create new webhook v2 integration

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"
}

Example: Update a webhook v2 integration configuration

curl https://api.bigpanda.io/resources/v2.1/integrations/ \
  --request POST \
  --header 'Content-Type: application/json' \
  --data 
'{
    "workflow_config": {
        "events": {
            "default": {
                "enabled": false
            },
            "incident#new": {
                "enabled": true,
                "path": "/incident/{{incident.id}}",
                "headers": {
                    "Authorization": "Bearer {{incidentTags.itd_applications_1}}"
                },
                "body": {
                    "incident_start": "{{incident.start}}"
                }
            },
        },
        "config": {
            "base_url": "https://webhook.site/37c633fb-d2ed-4832-abdf-217723bf350b"
        }
    }
}'

Example: Retrieve all webhook v2 configurations

curl https://api.bigpanda.io/resources/v2.1/integrations \
  --request GET \
  --header 'Content-Type: application/json' \

Example: Retrieve a webhook v2 configuration

curl https://api.bigpanda.io/resources/v2.1/integrations/ \
  --request GET \
  --header 'Content-Type: application/json' \

Example: Delete a webhook v2 integration

curl https://api.bigpanda.io/resources/v2.1/integrations/ \
  --request DELETE \
  --header 'Content-Type: application/json' \

Dynamic Variables API

The available dynamic variables API allows you to retrieve a list of incident and alert fields that can be used as a variable within outbound messaging templates and workflows.

This endpoint will return all dynamic variables available for use in a webhook v2 integration configuration. This includes a list of standard system fields as well as any unique incident and alert tags created by your organization.

Relevant Permissions

Roles with the following permission can access the Dynamic Variables 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.

Available routes and actions

API endpoint

https://api.bigpanda.io//resources/v2.1/fields-resolver/workflows 

Supported methods

GET

Dynamic variables object

Each dynamic field includes a title and value. The title is the user or system-defined name of the field. The value can be placed within double handlebars to use it as a variable in configurations. For example: {{incidentTags.affected_services}}

The dynamic variables retrieval returns fields for these categories:

Field name

Description

incident

Fields specific to share triggers.

incidentTags

Incident tags that are active for the organization.

primaryAlert

Fields related to the most severe, oldest alert associated with the incident.

primaryAlertTag

Alert tags that are active for the organization and could be associated with the primary alert.

metadata

Fields related to the share itself.

links

Direct links to the incident for different reader permissions.

assignee

Fields to reference the user assigned to the incident in BigPanda.

assigner

Fields to reference the user who assigned the incident in BigPanda.

additional_fields

Additional fields tied to AI and advanced features.

Example: Retrieve all available dynamic variables

Only webhook v2 dynamic variables will be retrieved

Custom email templates have a different set of available variables than webhook v2 integrations. Fields retrieved by the Dynamic Variables API are explicitly for webhook v2 and may not be available for email templates. See our dynamic variables documentation for the list of fields available for email templates.

{
    "status": 200,
    "data": {
        "incident": [
            {
                "title": "id",
                "value": "incident.id"
            },
            {
                "title": "alerts_array",
                "value": "incident.alerts_array"
            }
        ],
        "incidentTag": [
            {
                "title": "Affected Services",
                "value": "incidentTags.affected_services"
            },
            {
                "title": "tags_array",
                "value": "incidentTags.tags_array"
            }
        ],
        "primaryAlert": [
            {
                "title": "id",
                "value": "primaryAlert.id"
            },
            {
                "title": "maintenance",
                "value": "primaryAlert.maintenance"
            }
        ],
        "primaryAlertTag": [
            {
                "title": "host",
                "value": "primaryAlert.tags.host"
            },
            {
                "title": "health_rule",
                "value": "primaryAlert.tags.health_rule"
            }
        ],
        "metadata": [
            {
                "title": "environmentName",
                "value": "metadata.environment_name"
            },
            {
                "title": "message",
                "value": "metadata.message"
            }
        ],
        "links": [
            {
                "title": "previewUrl",
                "value": "links.preview"
            },
            {
                "title": "consoleUrl",
                "value": "links.console"
            },
            {
                "title": "timelineUrl",
                "value": "links.timeline"
            }
        ],
        "assignee": [
            {
                "title": "name",
                "value": "assignee.name"
            },
            {
                "title": "username",
                "value": "assignee.username"
            }
        ],
        "assigner": [
            {
                "title": "name",
                "value": "assigner.name"
            },
            {
                "title": "username",
                "value": "assigner.username"
            }
        ],
        "additional_fields": [
            {
                "title": "similarities",
                "value": "similarities"
            },
            {
                "title": "relatedChanges",
                "value": "relatedChanges"
            }
        ]
    }
}

Available dynamic variables

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