PagerDuty

A PagerDuty channel turns Fleetera alerts into PagerDuty incidents on one PagerDuty service. Fleetera talks to PagerDuty's Events API v2 directly, so there is no relay to host and no payload to map. You supply the service's integration key; Fleetera does the rest.

The incident follows the alert through its life:

What a PagerDuty channel needs

There is no Include resolve notifications switch on a PagerDuty channel. Resolves are always sent, so an incident never stays open in PagerDuty after its alert has resolved in Fleetera.

Create the integration in PagerDuty

Choose the service region

PagerDuty runs separate US and EU service regions, each with its own events address. An EU account's web address has eu in it (your-subdomain.eu.pagerduty.com); a US account's does not. Choose EU or US to match. Fleetera sends EU events to events.eu.pagerduty.com and US events to events.pagerduty.com.

Add the channel in Fleetera

PagerDuty channels are managed under Notifications → Channels. Choose Create channel, set the type to PagerDuty, paste the integration key, pick the service region, and adjust the severity mapping if you want something other than the default.

Fleetera checks the key's shape before saving, so a key that is not 32 letters and digits is rejected in the form rather than discovered on the first alert.

Channels can also be managed through the platform API:

POST /notification-channels
Content-Type: application/json

{
  "name": "Ops on-call",
  "type": "pagerduty",
  "config": {
    "routingKey": "0123456789abcdef0000000000000000",
    "region": "eu",
    "severityMap": { "warning": "error" }
  }
}

A severity the request leaves out keeps its default. The response carries the key masked and the complete map:

{
  "id": "0b8f2c1e-9d3a-4f57-bb20-2c6f0a1e4d9a",
  "name": "Ops on-call",
  "type": "pagerduty",
  "config": {
    "routingKeyMasked": "••••0000",
    "region": "eu",
    "severityMap": { "info": "info", "warning": "error", "critical": "critical" },
    "includeResolved": true
  },
  "enabled": true,
  "hasSecret": true,
  "secretShownOnce": null
}

includeResolved is always true for a PagerDuty channel, and a request that sets it to false is rejected.

Use a provisioned secret

Instead of pasting the integration key, a channel can use a secret that Fleetera staff provision for your organization. Contact Fleetera support to have the key provisioned under a name, for example ops-pagerduty. Nobody then pastes the key into the channel dialog.

In the channel dialog, under Integration key, choose Provisioned secret and pick the name. The list shows only the secrets that fit this channel type. Paste stays the default. If none fits, the dialog says so, and you paste the key instead.

• When Fleetera staff rotate the secret, later deliveries use the new key. You do not edit the channel.
• The channels list shows the secret's name and the region, for example Provisioned: ops-pagerduty · EU region.
• To switch an existing channel, open Edit channel, choose Provisioned secret, pick the name, and choose Save changes. Saving discards the stored key, so to switch back you choose Paste and enter a key again.

Through the API, send "secretRef": { "name": "ops-pagerduty" } in config in place of routingKey. Send one or the other, never both. A name that is not provisioned for your organization is refused with a 422 and the code secret_ref_not_found; a provisioned value that is not a valid integration key is refused with secret_ref_invalid.

What PagerDuty receives

Each Fleetera alert is its own incident. Fleetera derives a key from the alert itself and sends it as PagerDuty's dedup_key, so every event about one alert lands on the same incident:

• A repeat notification for an alert that is still firing goes to the incident that is already open, rather than opening a second one.
• The next time the same rule fires on the same asset and variable, after the earlier alert resolved, it is a new Fleetera alert, so it gets a new key and a new incident. A late resolve or acknowledgement of the earlier alert can never change the new incident.

When an alert fires, the incident carries:

• A summary that names the severity, the rule, the asset and its site, and the measured value against its threshold, for example [CRITICAL] Overheat: Turbine 7 at North Ridge · temperature 99 °C (threshold 80 °C).
• The source (the asset), the component (the variable), the group (the site) and the class (the rule type).
• Custom details: the asset, site, variable, value, threshold, rule, severity, when it triggered, the rule's corrective action and time to respond when they are set, and links to the alert and the rule in Fleetera.
• Two links, View alert in Fleetera and View rule in Fleetera.

When the alert is acknowledged in Fleetera, from its page or in bulk from the alerts list, Fleetera acknowledges the incident. Only channels that received the alert's trigger are told: an alert still waiting in its grouping window has opened no incident, so there is nothing to acknowledge. Taking an acknowledgement back in Fleetera (Un-ack) sends nothing, because PagerDuty has no way to undo one; the incident stays acknowledged until it resolves.

When the alert resolves, Fleetera resolves the incident. This happens even when Notify on resolve is off on the routing policy that delivered the alert: that switch governs the other channel types, never an incident tool.

Send a test incident

Before you route real alerts through the channel, confirm it reaches PagerDuty. Use Send test on the channel row, or the API:

POST /notification-channels/{channelId}/test

Fleetera triggers a clearly-marked test incident, named Fleetera incident tool test and prefixed [TEST], and resolves it straight away, so nothing is left open. While it is open, it is a real incident on the service, so tell your on-call team before you test. The response reports both steps:

{
  "delivered": true,
  "deliveryId": "a1b2c3d4-e5f6-4711-89ab-0123456789ab",
  "status": "sent",
  "httpStatus": 202,
  "attempts": 1,
  "error": null
}

delivered is true only when PagerDuty accepted both the trigger and the resolve. When the trigger landed and the resolve did not, the channel row says Trigger sent, resolve failed, and error starts with resolve:. The test incident may then still be open: resolve it in PagerDuty.

Reading the delivery log

Each channel's detail page lists its deliveries. A PagerDuty channel records one row per call: the trigger (marked Initial, or Repeat for a repeat notification), the Acknowledge and the Resolve. A test send records two rows, the test trigger and its resolve, both marked Test send.

When a delivery does not succeed, the details column carries the HTTP status, followed by PagerDuty's own message in parentheses when it returned one. The integration key never appears in the delivery log.

Retries

A transient failure, a 429, a 5xx or a network error, is retried up to 5 attempts in total, with exponential backoff and jitter running from about 30 seconds out to about 8 minutes. When PagerDuty sends a Retry-After header, Fleetera waits for the interval it asked for, bounded to between 1 second and 15 minutes.

A 400 and every other 4xx except 429 is permanent: the event is not retried and the delivery is marked failed.

Updating, rotating, and removing a channel

You can rename a channel, change its region and its severity mapping, and enable or disable it at any time. A channel's type cannot be changed.

To rotate the key, create a new Events API V2 integration on the service in PagerDuty, then choose Replace next to the masked key in Fleetera and paste the new one. Leaving the masked key in place keeps the stored one. A channel that uses a provisioned secret is rotated by Fleetera staff, with no edit to the channel.

Disabling a channel stops new deliveries to it, which makes it the fastest way to stop paging without losing its configuration.