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.
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 |
|
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: | 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:
| 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 |
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 |
|
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 | 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 | |
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 | |
incidentTags.<tag_id> | The value(s) of the specified incident tag as related to the incident. | Array of strings |
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:
| Array of objects | Webhook v2 |
relatedChanges | Schema definitions for all RCC relations. Attributes:
| Array of objects | Webhook v2 |