The Rulesets feature allows you to route events to an endpoint and create collections of event rules, which define sets of actions to take based on event content. Accounts with Free, Starter (legacy), Team (legacy), and Professional plans will have access to a single global ruleset, while Business, Enterprise for Incident Management and Digital Operations (Legacy) plans will now have the ability to create multiple, unlimited global rulesets. For these higher-tier plans, each ruleset will have an individual endpoint and they can be associated with specific Teams, giving Team Managers edit-access to their rules.

❗️

End-of-Life

Rulesets and Event Rules webpages reached end-of-life on January 31, 2025 and are no longer visible in the PagerDuty web app. We highly recommend that you migrate to Event Orchestration as soon as possible so you can take advantage of the new functionality, such as improved UI, rule creation, APIs and Terraform support, advanced conditions, and rule nesting.

Access and modifications to event rules are still possible via the API.

Ruleset Types

There are two ways to organize event rules in your account, based on your integration use case:

• Global Rulesets: When a new integration event stream has more than one service destination, you can use global event rules and a global Integration Key to ingest and route your events to the right service. If your existing service integrations have the same event stream integrated into multiple services, consider migrating those integrations to a global ruleset and use routing rules to direct events to the correct services. Global rulesets support event rules for email integrations, but do not support Custom Event Transformers.
• Service Event Rules: When integrations already exist on a Service, you can use Service Event Rules to evaluate your events instead of migrating them to a global event rule. Service event rules support Custom Event Transformers, but do not support event rules for email integrations.

Global Rulesets

Events sent to a global ruleset Integration Key or emails sent to a global email address will be evaluated by the destination global ruleset. In order to create alerts and incidents on a destination service, a global event rule must have Create an incident on a service selected as one of its actions. When an event is routed to a service that contains service event rules, then it will also be evaluated by service event rules at the time of event ingestion, after global event rules have been evaluated.

All plans will have access to a Default Global Ruleset that is available out-of-the-box. Accounts on Business, Enterprise for Incident Management, and Digital Operations (Legacy) plans have the option to create multiple additional rulesets, and they can opt to assign these additional rulesets to Teams.

To view your rulesets using the API:

• Use the List Rulesets endpoint to list the details for all rulesets on your account, including a ruleset’s ID.
• Use the List Service Event Rules endpoint to see the rules for a specific ruleset.

Create Multiple Rulesets and Assign Teams

🚧

Required User Permissions

• Account Owners, Admins and Global Admins can create/edit/delete rulesets by default. Users with Team Manager roles can create/edit/delete rulesets for their assigned Team.
• Business, Enterprise for Incident Management and Digital Operations (Legacy) plans have the ability to create multiple, unlimited global rulesets, each of which can be assigned to a Team. Note: If you do not assign a new ruleset to a team, then it will behave as an additional global ruleset.
• Account Owners and Admins have view access to all rulesets. Users below Admin will only be able to view rulesets associated with Teams they are assigned to.

Please refer to our API documentation for more information on how to create a new ruleset. If you wish to assign a Team, you can include the Team’s ID in the payload of your request.

Service Event Rules

Events that are sent to any service Integration Key will be evaluated by the event rules present on that service at the time that an event is ingested. This behavior is different from global rulesets, which apply rules to all inbound events sent to a global integration key. Service event rules are available on all plans.

Create Service Event Rules

Please refer to our API documentation for more information on how to create new event rules for a service.

Create Event Rules

Event rules allow you to set actions that should be taken on events that meet your designated rule criteria. You can choose whether you would like criteria-satisfying events to trigger incidents, or if you would like them to be suppressed and viewable in your Alerts table. Depending on your plan and account add-ons, you may have additional actions to take on incidents or suppressed alerts.

Event rules must be created in a global ruleset or on a service. Follow the instructions in the above sections to determine where you are creating your event rules, and then proceed with the following steps.

Both Global Event Rules and Service Event Rules are managed via API. Please refer to our API documentation to create a new Global Event Ruleset or Service Event Rule.

🚧

Event Rule Limitations

Each ruleset has a limitation of 25,000 event rules. Once the limit of 25,000 rules is met, users will not be able to add any further event rules to the ruleset.

Recommended Preparation

We recommend sending an alert to your PagerDuty account in order to inspect the alerts’ JSON key:value pairs and build rule conditions from there. Please read our API documentation for more information on how to send a simple alert into PagerDuty.

Example in CURL:

curl --location --request POST 'https://events.pagerduty.com/v2/enqueue' \
--header 'Content-Type: application/json' \
--data-raw '{
 "payload": {
   "summary": "Example alert on host2000.example.com",
   "timestamp": "2020-06-17T08:42:58.315+0000",
   "source": "monitoringtools:cloudvendor:central-region-dc-01:002000987:cluster/api-stats-prod-003",
   "severity": "info",
   "component": "postgres",
   "group": "prod-datapipe",
   "class": "deploy",
   "custom_details": {
     "ping time": "1600ms",
     "load avg": 0.90
   }
 },
 "dedup_key": "uniquededupkey",
 "routing_key": "R015DM1NF3UYE4NSWN8WBF6FS062ZZZZ",
 "images": [{
   "src": "https://www.pagerduty.com/wp-content/uploads/2016/05/pagerduty-logo-green.png",
   "href": "https://example.com/",
   "alt": "Example text"
 }],
 "links": [{
   "href": "https://example.com/",
   "text": "Link text"
 }],
 "event_action": "trigger",
 "client": "Sample Monitoring Service",
 "client_url": "https://monitoring.example.com"
}'

Configure Conditions

Depending on your preferences, indicate the condition(s) that should be met when this event rule searches inbound events. Below are some concepts to keep in mind when configuring conditions:

Path References

📘

Note

Field names are case-sensitive.

Events Sent Through the API: You can use the JSON field names directly, i.e. description. For nested fields, separate names with a dot (.), i.e. payload.summary. If you are sending data through additional fields, enter them exactly as they are sent to PagerDuty. For example, if your events have a tags field, enter that field name in your rule condition as tags.
Events Sent Through Email (Note: Only available in global rulesets, not with service event rules): Rules may be based on the content of an email by entering the appropriate email field as the event field. The most common email fields are:

• headers.from.0.address (the from address)
  ** Note: .0.address refers to the 1st position in a list of emails. If you would like to generally search through a list of emails (either in the "to" field or the "from" field), please set to headers.from or headers.to
  • headers.subject (the subject line)
  • body (the email body)

If your monitoring tool sends emails with custom headers, you can create rules based on those headers by including the prefix headers in front of the email header name when you enter that field name in your rule condition.

Subcondition Operators

Subcondition operators are used to determine how the chosen event field is filtered:

• The field contains/does not contain a value.
• The field equals/does not equal a value (this operation requires the field to be passed in as a string).
• The field exists/does not exist.
• The field matches/does not match a regular expression. Regular expressions must use RE2 syntax. Note that unlike service-level event rules, global rules only support one (e.g. the first) capture group within the regex.

📘

Negative Operations

Rules with negative operations, such as does not contain or does not equal, will match events that do not contain your specified value and events that do not contain the field at all. As an example:

• severity field does not equal critical

This will match events where the severity field does not equal critical and events that do not contain a severity field at all.

If you'd like to avoid this, you must add an additional condition that matches only when the field exists. For example:

When all conditions are true:

• severity field exists
• severity field does not equal critical

Note that you must configure the rule so that all conditions must be true for the rule to match.

Customize Event Fields (Optional)

Dynamic Field Enrichment & Extraction

Dynamic Field Enrichment & Extraction is a tool used to normalize event payloads using Event Rules. This capability allows you to copy important data from any combination of source event fields into any PagerDuty Common Event Format (CEF) field. Translate difficult machine terms and code into helpful context for responders so they can effectively respond to the problem. Dynamic Field Enrichment & Extraction can also be used to enhance PagerDuty AIOps capabilities by customizing alerts, influencing the Intelligent Alert Grouping and Intelligent Triage machine learning algorithms.

📘

Custom Event Fields vs. Custom Fields on Incidents

This feature is intended to customize event fields within Alerts, as opposed to creating custom fields in the incident UI. To create the latter, please read Custom Fields on Incidents.

📘

Availability

This feature is available with the PagerDuty AIOps add-on. Please contact our Sales Team if you would like to purchase this product.

Dynamic Field Enrichment & Extraction is composed of two functions:

• Create Custom Variables: Capture snippets from a source event using regex matching for later use.
• Replace Common Event Format Fields: Enrich and update and CEF field or even create new key values within the Custom Details object using custom variables. When events are sent to PagerDuty, they are transformed into Common Event Format. Previously, Event Rules could only replace Summary or add a Deduplication Key, and these abilities were limited to a direct mapping from one field as a full replacement. Now, this ability is extended to replace any CEF field or even create new key values within the Custom Details object.

Dynamic Field Enrichment & Extraction is available with both Global Event Rules and Service Event Rules. For Service Event Rules, custom variables must extract from CEF fields of the event payload, where for Global Event Rules, custom variables can extract from any field of the event payload.

Global and Service Event Rules are evaluated against the original event. Fields created from Global Event rules via Dynamic Field Enrichment & Extraction cannot be evaluated by Service Event Rules.

Configure Dynamic Field Enrichment & Extraction

When using the API to create service event rules or event rules in a ruleset, you can use the extractions object in your request payload to define the source, value, and regex.

Set a Deduplication Key with Event Rules

The dedup_key field is used to merge events into a single alert. Events with the same dedup_key can update the status of the alert they are automatically merged into.

Below is an example of a ruleset configured to set a deduplication key using the details.error_summary field:

{
  "ruleset": {
    "id": "14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
    "position": 0,
    "disabled": false,
    "catch_all": false,
    "self": "https://api.pagerduty.com/rulesets/0e84de00-9511-4380-9f4f-a7b568bb49a0/rules/14e56445-ebab-4dd0-ba9d-fc28a41b7e7b",
    "conditions": {
      "operator": "and",
      "subconditions": [
        {
          "operator": "contains",
          "parameters": {
            "value": "mysql",
            "path": "details.host"
          }
        }
      ]
    },
    "time_frame": {
      "active_between": {
        "start_time": 1577880000000,
        "end_time": 1580558400000
      }
    },
    "actions": {
      "annotate": {
        "value": "This incident was created by a Global Event Rule"
      },
      "route": {
        "value": "PI2KBWI"
      },
      "priority": {
        "value": "PCMUB6F"
      },
      "severity": {
        "value": "warning"
      },
      "extractions": [
        {
          "target": "dedup_key",
          "source": "details.error_summary",
          "regex": "Host (.*) is experiencing errors"
        }
      ]
    }
  }
}

Add or Replace the Summary Field with Event Rules

The summary field is used to create the incident title. Titles should be descriptive and tell responders what is happening.

Below is an example of a rule using a custom variable to replace the default summary value with a custom error_title field value:

{
  "rule": {
    "actions": {
      "annotate": null,
      "automation_actions": [],
      "event_action": null,
      "extractions": [
        {
          "regex": null,
          "source": null,
          "target": "summary",
          "template": "{{newSummary}}"
        }
      ],
      "priority": null,
      "route": {
        "value": "P9XD19J"
      },
      "severity": null,
      "suppress": null,
      "suspend": null
    },
    "catch_all": false,
    "conditions": {
      "operator": "and",
      "subconditions": [
        {
          "operator": "contains",
          "parameters": {
            "path": "payload.source",
            "value": "webAPI"
          }
        }
      ]
    },
    "disabled": false,
    "id": "a1582b38-e753-486a-bc5c-bb7c6895e00c",
    "position": 0,
    "self": "https://api.pagerduty.com/rulesets/1d9089cd-fc3a-406e-9ddc-625bbeb43601/rules/a1582b38-e753-486a-bc5c-bb7c6895e00c",
    "time_frame": null,
    "variables": [
      {
        "name": "newSummary",
        "parameters": {
          "path": "payload.custom_details.error_title",
          "value": "(.*)"
        },
        "type": "regex"
      }
    ]
  }
}

Using Dynamic Field Enrichment & Extraction for Email Events

Dynamic Field Enrichment & Extraction capabilities are available only for email events sent to Global Event Rules. Users can extract from the email event using regex matching into multiple variables. Currently, only Summary and Dedup_Key Common Event Fields can be replaced for email events.

Service Event Rules do not apply to emails because they aren’t CEF and therefore, dynamic field enrichment & extraction capabilities are not available for email service integrations.

Enhancing Alert Grouping Capabilities

Dynamic Field Enrichment & Extraction can be powerfully leveraged for improving the accuracy for Intelligent Alert Grouping and Content Based Alert Grouping. This capability can add and replace key information from the raw event payload to create more contextualized alerts, allowing for more flexible and accurate alert grouping options.

Configure Actions

Determine which actions you would like this rule to take when an event meets the condition(s) you set.

Please refer to our API documentation for more information on the available actions.

Paused Incident Notifications

As a feature of Rulesets, paused incident notifications allows rules to be set to create alerts, but pause incident creation and notifications for a predefined amount of time. During the pause period, new alerts will be viewable in the Alerts table with a Suspended status. These suspended alerts have new actions, allowing users to Trigger an incident from the alert during the pause period, or Resolve the alert, preventing the incident and its notifications from being created altogether.

📘

Availability

• The Paused Incident Notifications functionality is part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.
• Paused Incident Notifications is only available on incidents generated by our Events API, and does not work with those generated from our REST API.

To configure paused incident notifications, please refer to our API documentation for more information.

View and Take Action on Paused Alerts

To view alerts in a paused state, navigate to the Alerts table in the upper menu of the web app. Alerts with paused incident notifications will have a Suspended status:

To take action on a paused alert:

1. Click the incident title to view its details page.
2. On the right hand side, click Trigger to trigger an incident and send notifications, or Resolve if you would like to resolve the alert without triggering an incident/notifications. You will see a green dialog that confirms that the alert has been triggered or resolved.

The pause period and action taken will also appear in the Alert Log timeline, accessible by clicking an alert's title to view the detail page:

Suppress, but Create Triggering Thresholds with Event Rules

Receive PagerDuty notifications only when your customized alert conditions breach your specified limits. In this way, responders effectively reduce alert noise without missing critical issues.

📘

Availability

The Threshold Alerts functionality is part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

To configure triggering thresholds for suppressed incidents, please refer to our API documentation for more information.

Set Severity with Event Rules

For events that do not have a severity level (such as emails), users can define one, or a new severity level can be set. All current pricing plans include incident severity.

To set severity, please refer to our API documentation for more information.

Set Incident Urgency with Event Rules through Dynamic Notifications

Severity can be used for Dynamic Notifications, which are defined by the service settings. To use Dynamic Notifications, the events must be routed to a service that sets Dynamic Notifications based on severity levels.

With severity controlled via event rules and the service configured to use dynamic notification, you can control the incident urgency.

Set Priority with Event Rules

Incident priority allows the classification of incidents based on a level of prioritization. Incident priority must be enabled on your account before it can be set with event rules.

To set priority, please refer to our API documentation for more information.

Add a Note to an Incident with Event Rules

Notes can be used to help responders resolve incidents quicker by including information or links related to the system that the event comes from.

📘

Notes

• Adding notes via event rules is available with our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.
• The note is added when an incident is created. If a new alert is deduplicated into the incident, then the deduplicated alert will not add an additional note nor change the original.

To add a note with event rules, please refer to our API documentation for more information.

Set a Custom Trigger / Resolve Action with Event Rules

If you would like to automatically trigger an alert or resolve an alert based on your event rule conditions, under Enrichment & Transformations, please refer to our API documentation for more information on configuring this action. All pricing plans include incident custom trigger/resolve actions with event rules.

Automated Triggers

Automated Triggers allow response teams to easily define a dynamic webhook using event rules, sending a custom payload to a specified endpoint. This enables responders to automate actions like restarting a server, clearing logs, and reverting bad deploys. The payload can be set using a combination of several predefined variables, created using Dynamic Field Enrichment and Extraction. Automated Triggers can be created using both global event rules and service level event rules.

📘

Availability

Automated Triggers are a feature of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Configure Automated Triggers

To configure automated triggers, please refer to our API documentation for more information.

Use Automated Triggers

Once the rule is created, a custom push-button action will be available the next time the rule is applied. Users can find the Automated Triggers action in the More... dropdown on the incident details page, and activity related to the custom rule action will be visible in the incident timeline.

There is a limit of one Automated Trigger per rule. If Intelligent Alert Grouping is enabled on a Service, each additional alert grouped to the incident can add an additional unique action button, up to a limit of 5 buttons.

A modal will appear when the Automated Triggers action is clicked, and users can confirm the details of the webhook payload (fields were set in the rule configuration phase). For all webhooks, the PagerDuty incident ID will be included as a mandatory field. If the action is triggered, a response log will be shown in the incident timeline to let users know if the webhook was successfully received.

Configure Time Frame

While configuring a rule via the API, you can optionally define a specific time frame or schedule for when you would like this rule to be active using the time_frame object.

If you omit time_frame from your request, this rule will always run (24/7/365) when your conditions are met.

Scheduled Event Rules

You can gain a greater degree of control over your event rules by detailing a single specific time in the future in which they will be active. This can be useful for testing rules and for planned maintenance. Users can then specify what actions are to be performed within this specific time window. For instance, if you schedule a rule to be active during a single hour window, and the action set was to suppress alerts, alerts would be suppressed during that hour, and once it ended they would begin generating incidents again.

📘

Availability

Scheduled Rules functionality is available with our Business, Enterprise for Incident Management and Digital Operations (Legacy) plans, or as part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Recurring Event Rules

If there are specific hours of the day or day(s) within a week when you would like an event to follow a particular rule, you can set its activity on an automatic, weekly recurring schedule. This feature is specific to each individual event rule and you can make additional changes, such as changing severity/priority, based on time of day.

📘

Availability

The Recurring Event Rules functionality is available with our Business, Enterprise for Incident Management and Digital Operations (Legacy) plans, or as part of our PagerDuty AIOps product, which is purchased separately from the core PagerDuty platform. Please contact our Sales Team if you would like to purchase this product.

Send Test Events

🚧

Unsupported Integration Types

The following types of integrations cannot use ruleset integration keys:

• Integrations that connect via account authorization are not supported.
• Custom Event Transformer integrations are not supported.
• Integrations that use the REST API are not supported.

Send Events to a Global Ruleset

Each global ruleset will have a routing integration key, as well as an HTTP endpoint for API and email address that you can use for routing.

The HTTP endpoint used for rulesets is https://events.pagerduty.com/v2/enqueue. You can view a ruleset's routing key by making a request to the Get a Ruleset endpoint. A ruleset's email address will follow the formula routing_key@your_subdomain.pagerduty.com.

Use this information to send events based on your preferred integration method:

• Use the Integration Key to integrate with your preferred tool.
• Use the Integration Key to send an event through one of the Events APIs.
  • If using the V2 events API, use your routing Integration Key as your routing_key value in your event JSON.
  • If using the V1 events API, use your routing Integration Key as your service_key value in your event JSON.
• Use the Email address to send email events.

📘

Note

Integration Keys are case-sensitive.

This will allow you to test how your event rules will modify them and take the actions configured in previous steps. Your event rule is now complete! If you would like to create more event rules, repeat steps 1-4 as needed.

Send Events to Service Event Rules

Add your preferred tool integration or a Custom Event Transformer integration on the service where you configured the above rule(s). Once you have added the integration to your service, you will be directed to the Integrations tab, where you can access its Integration Key:

Use this Integration Key to complete your integration and send test events to your service. This will allow you to test how your event rules will modify them and take the actions configured in previous steps. Your event rule is now complete! If you would like to create more event rules, repeat steps 1-4 as needed.

Edit Rulesets and Event Rules

Edit a Global Ruleset's Event Rules

Please refer to our API documentation for more information on editing event rules.

Edit a Global Ruleset’s Details

Please refer to our API documentation for more information on editing rulesets.

Edit Service Event Rules

Please refer to our API documentation for more information on editing a service's event rules.

Disable Event Rules

If you would like to pause an event rule’s activity, you can disable and re-enable it at a later time. This feature allows you to manually initiate integration-specific disablement during maintenance or testing on a tool.

Please refer to our API documentation for more information on disabling event rules.

Troubleshooting Event Rules

If None of Your Rules Are Working

This may be because you have not set up the integration key correctly in your monitoring tool. For event rules to work, you must use the integration key for the event rules you have configured.

Service Event Rules : You will find your integration key by navigating to Services Service Directory click the name of the service that has your desired event rule configured select the Integrations tab. You will see your integration key to the right of the integration’s name.

Global Rulesets: You can view a ruleset's routing key by making a request to the Get a Ruleset endpoint.

If you are sending events through the Events API, use this integration key in the service_key field (Events API V1) or the routing_key field (Events API V2).

If One of Your Rules Is Not Working

This may be because you have not entered the field name correctly in the rule conditions. The field name is based on the data that is sent to PagerDuty, and is not necessarily the same as the field name visible in the alert or incident in PagerDuty. Refer to the data in your monitoring tool or integration for the correct field name.

For nested fields, format the field name with periods separating each level. For example, field_group.sub_field.another_sub_field.

If you have confirmed your field names are set up correctly, you may have a rule that is too broad that is ordered before the rule that is not working. Re-order your rules so that more specific rules are listed first.

You may also want to check for rules with negative conditions ("does not contain" or "does not equal"), as these rules can match many events that do not contain the specified field.

For nested fields, format the field name with periods separating each level of the object path. For example, field_group.sub_field.another_sub_field.

Switch to Service Orchestrations

Service Orchestrations provide updated functionality to Service Event Rules. If you would like to switch from Service Event Rules to Service Orchestrations, please read our Event Orchestration documentation.

FAQ

Are email integration filters/rules, or custom event transformers supported?

Are events transformed into our Common Event Format (CEF)?

What happens to events that don’t match any rules?

Is there a way to bulk add/delete/edit global event rules?

Once an event is routed to a service from my global event rules, will the event rules I set up on my service be respected as well?

Can I send a second event with the same dedup_key and have it follow different actions?

What happens if I do not create a deduplication key for an email sent to a ruleset?

Is there a difference between the types of events processed by global event rules vs. service event rules?

Why wasn't my event suppressed by a rule?