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