# PagerDuty alert task

> Learn how to send PagerDuty alerts from Synnax when statuses change.

The PagerDuty integration watches status keys and opens or resolves PagerDuty incidents when they change. Error, warning, and info variants send an event with the matching severity. Success resolves the open incident. Events are deduplicated by status key, so repeated changes update the existing incident.

The integration runs on the Synnax Core, not on the Driver, so the Core must reach `events.pagerduty.com` over HTTPS.

This task follows the standard [task lifecycle](https://docs.synnaxlabs.com/reference/driver/task-basics#task-lifecycle).

## Prerequisites

1. A [PagerDuty](https://www.pagerduty.com/) account.
2. A PagerDuty service with an Events API v2 integration. In PagerDuty, open `Services` -> `Service Directory`, select the service, then `Integrations` -> `Add Integration` -> `Events API v2`.
3. The 32-character integration key (routing key) from that integration.

## Severity mapping

| Synnax status variant | PagerDuty severity                                           |
| --------------------- | ------------------------------------------------------------ |
| Error                 | `error`, or `critical` when the alert sets `errors_critical` |
| Warning               | `warning`                                                    |
| Info                  | `info`                                                       |
| Success               | Resolves incident                                            |

## Supported operating systems

| Platform | Status      |
| -------- | ----------- |
| Windows  | ✓ Supported |
| Linux    | ✓ Supported |
| macOS    | ✓ Supported |
| Docker   | ✓ Supported |

## Task configuration reference

| Parameter     | Type   | Required | Default | Description                                                                                                                     |
| ------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `routing_key` | string | Yes      | -       | 32-character PagerDuty Events API v2 Integration Key                                                                            |
| `alerts`      | array  | Yes      | -       | List of [alert configurations](https://docs.synnaxlabs.com/reference/driver/pagerduty/alert-task#alert-configuration-reference) |

## Alert configuration reference

Each alert maps a Synnax status key to a PagerDuty event. The task needs at least one alert that is not disabled.

| Parameter         | Type    | Required | Default | Description                                                                  |
| ----------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------- |
| `status`          | string  | Yes      | -       | The Synnax status key to watch                                               |
| `disabled`        | boolean | No       | `false` | Excludes the alert from the task                                             |
| `errors_critical` | boolean | No       | `false` | Map error variant to `critical` PagerDuty severity instead of `error`        |
| `component`       | string  | No       | `""`    | Component of the source machine (e.g., `"engine-1"`)                         |
| `group`           | string  | No       | `""`    | Logical grouping of components (e.g., `"engines"`)                           |
| `class`           | string  | No       | `""`    | Class/type of the event (e.g., `"engine-failure"`). Named `class_` in Python |

## How-to

**Console**

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/device-drivers/pagerduty/alert-task/create-dark.mp4#t=0.001)

**Python**

Create and run an alert task

```python
import synnax as sy

client = sy.Synnax()

# Create a status to watch
STATUS_KEY = "example-pagerduty-status"
client.statuses.set(
    sy.Status(
        key=STATUS_KEY,
        name="Engine 1",
        variant="success",
        message="Engine 1 is healthy",
    )
)

# Create the PagerDuty alert task
alert_task = sy.pagerduty.AlertTask(
    name="Example PagerDuty Alert",
    routing_key="<your-32-character-integration-key>",
    auto_start=False,
    alerts=[
        sy.pagerduty.Alert(
            status=STATUS_KEY,
            errors_critical=True,
            component="engine-1",
            group="engines",
            class_="engine-failure",
        ),
    ],
)

# Configure the task with Synnax
client.tasks.configure(alert_task)

# Start the task - it will watch for status changes
with alert_task.run():
    # Trigger a PagerDuty incident by setting status to error
    client.statuses.set(
        sy.Status(
            key=STATUS_KEY,
            name="Engine 1",
            variant="error",
            message="Engine 1 is down",
            description="Connection to database lost",
        )
    )
    sy.sleep(5)

    # Resolve by setting status back to success
    client.statuses.set(
        sy.Status(
            key=STATUS_KEY,
            name="Engine 1",
            variant="success",
            message="Engine 1 recovered",
        )
    )
    sy.sleep(3)
# Task automatically stops when exiting the context manager
```