PagerDuty

Notification

Synopsis

Sends incident alerts to PagerDuty using the Events API v2, supporting event actions (trigger, acknowledge, resolve), severity levels, deduplication keys, and custom details for incident management.

Schema

- pagerduty:
    routing_key: <string>
    summary: <string>
    event_action: <string>
    dedup_key: <string>
    source: <string>
    severity: <string>
    component: <string>
    group: <string>
    class: <string>
    custom_details: <map>
    client: <string>
    client_url: <string>
    images: <image[]>
    links: <link[]>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
`routing_key`	N	`${PAGERDUTY_ROUTING_KEY}`	PagerDuty integration key (routing key)
`summary`	Y	-	Brief description of the incident
`event_action`	N	`trigger`	Action to perform: `trigger`, `acknowledge`, or `resolve`
`dedup_key`	N	-	Deduplication key to correlate trigger, acknowledge, and resolve events
`source`	N	-	Source of the event (e.g., hostname, service name)
`severity`	N	`info`	Severity level: `critical`, `error`, `warning`, or `info`
`component`	N	-	Component of the source machine responsible for the event
`group`	N	-	Logical grouping of components
`class`	N	-	Type or classification of the event
`custom_details`	N	-	Map of additional details to include with the incident
`client`	N	`VirtualMetric`	Name of the monitoring client
`client_url`	N	`https://www.virtualmetric.com`	URL of the monitoring client
`images`	N	-	Array of image objects with `src`, `href`, and `alt` fields
`links`	N	-	Array of link objects with `href` and `text` fields
`description`	N	-	Explanatory note
`if`	N	-	Condition to run
`ignore_failure`	N	`false`	See Handling Failures
`on_failure`	N	-	See Handling Failures
`on_success`	N	-	See Handling Success
`tag`	N	-	Identifier
`disabled`	N	`false`	When `true`, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration

Details

The pagerduty processor sends incident alerts to PagerDuty using the Events API v2.

Event Actions: Control incident lifecycle through event actions:

trigger: Create a new incident or add to an existing open incident with the same dedup_key
acknowledge: Acknowledge an open incident (prevents escalation)
resolve: Close an open incident

Deduplication Keys: The dedup_key field correlates related events. Multiple triggers with the same dedup_key are grouped into one incident. Use templates to create dynamic keys based on event data (e.g., cpu-{{server}}).

Severity Levels: Visual and behavioral indicators in PagerDuty:

critical: Highest severity, immediate attention required
error: Error condition requiring attention
warning: Potential issue, monitoring recommended
info: Informational message

Custom Details: The custom_details map passes additional context to responders. Its values are sent through unchanged — they are not template-expanded, unlike the string fields above. Put a field reference in summary or source if you need one resolved.

Images and Links: Enrich incidents with visual context and quick navigation:

Images: Include src (required), href, and alt fields
Links: Include href (required) and text fields

Template Support: Eight fields are template-expanded — summary, source, component, group, class, dedup_key, severity and event_action. Use {{field_name}} for the escaped value and {{{field_name}}} for the raw one. No other field is expanded, including client, client_url, images, links and the custom_details map.

For integration patterns with schema validation, see Schema Drift Detection.

Examples

Basic Alert

Triggering a critical incident...

{
  "alert_name": "High CPU Usage",
  "server": "prod-server-01",
  "cpu_usage": "95%"
}

- pagerduty:
    routing_key: "${PAGERDUTY_ROUTING_KEY}"
    summary: "Alert: {{alert_name}} on {{server}}"
    source: "{{server}}"
    severity: "critical"
    dedup_key: "cpu-{{server}}"

Critical incident created in PagerDuty...

Resolve Incident

Resolving a previously triggered incident...

{
  "alert_name": "High CPU Usage",
  "server": "prod-server-01"
}

- pagerduty:
    routing_key: "${PAGERDUTY_ROUTING_KEY}"
    event_action: "resolve"
    summary: "Resolved: {{alert_name}} on {{server}}"
    source: "{{server}}"
    severity: "info"
    dedup_key: "cpu-{{server}}"

Incident with matching dedup_key is resolved...

With Custom Details

Including additional context in the incident...

{
  "alert_name": "High CPU Usage",
  "server": "prod-server-01",
  "cpu_usage": "95%"
}

- pagerduty:
    routing_key: "${PAGERDUTY_ROUTING_KEY}"
    summary: "Alert: {{alert_name}} on {{server}}"
    source: "{{server}}"
    severity: "critical"
    component: "CPU"
    dedup_key: "cpu-{{server}}"
    custom_details:
      cpu_usage: "{{cpu_usage}}"
      server: "{{server}}"

Custom details appear in incident timeline...

With Images and Links

Adding visual context and navigation links...

{
  "alert_name": "Schema Drift Detected",
  "schema": "ASimNetworkSessionLogs"
}

- pagerduty:
    routing_key: "${PAGERDUTY_ROUTING_KEY}"
    summary: "{{alert_name}}: {{schema}}"
    source: "Data Pipeline"
    severity: "warning"
    component: "Schema Validation"
    dedup_key: "schema-{{schema}}"
    images:
      - src: "https://example.com/chart.png"
        href: "https://dashboard.example.com"
        alt: "Monitoring Chart"
    links:
      - href: "https://dashboard.example.com/schema"
        text: "View Schema Dashboard"

Incident includes embedded image and a link to the analytics view...

Schema Drift Alert

Alerting on schema validation failures...

processors:
  - check_schema:
      schema: "ASimNetworkSessionLogs"
      target_field: "schema_check"
      on_missing:
        - pagerduty:
            routing_key: "${PAGERDUTY_ROUTING_KEY}"
            summary: "Schema Validation Failed: ASimNetworkSessionLogs"
            source: "Data Pipeline"
            severity: "critical"
            component: "Schema Validation"
            group: "Data Quality"
            class: "Schema Drift"
            dedup_key: "schema-ASimNetworkSessionLogs"
            custom_details:
              is_valid: "{{schema_check.is_valid}}"

PagerDuty incident triggered when schema validation fails...

Synopsis​

Schema​

Configuration​

Details​

Examples​

Basic Alert​

Resolve Incident​

With Custom Details​

With Images and Links​

Schema Drift Alert​