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.

Reference Rulesets Advanced Configuration for more configuration options.

❗️

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

• The Account Owner, 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

📘

Case Sensitivity

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.

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.

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.

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.