PagerDuty Connections

PagerDuty connections let agents call the PagerDuty REST API to look up incidents, services, on-call schedules, and escalation policies. Authentication uses a PagerDuty API token.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Setup

1. Sign in to PagerDuty as an admin or account owner
2. Navigate to Integrations → API Access Keys (or open https://app.pagerduty.com/api_keys)
3. Click Create New API Key
4. Choose Read-only unless an agent must create or acknowledge incidents
5. Copy the generated token

Connection Parameters

Parameter	Type	Description
api_token	string	PagerDuty API token — sent as Authorization: Token token=<token>

Example Connection

{
  "display_name": "Production PagerDuty",
  "description": "Production PagerDuty account — used for incident lookup and on-call routing",
  "connection_details": {
    "pagerduty": {
      "api_token": "<token>"
    }
  }
}

Webhook Ingest (optional)

Send PagerDuty V3 webhook events into Firetiger as they happen. Events land in Iceberg tables under pagerduty/events/{event_type} (one table per event type, schema inferred on first event).

This is separate from the API connection above and can be enabled in addition to it. The API connection uses the api_token field; webhook ingest uses signing_secret.

1. Generate the webhook URL

In the connection’s settings, click Generate Webhook URL. Copy the URL that appears in the Webhook URL field.

2. Create the webhook subscription in PagerDuty

In PagerDuty, go to Integrations → Generic Webhooks (V3) (account-level) or Service Directory → service → Integrations → Webhooks (per-service), then + Add a Webhook:

• URL: paste the URL from step 1
• Events to subscribe to: pick the event types to forward (e.g. incident.triggered, incident.acknowledged, incident.resolved)

PagerDuty shows the signing secret once after saving. Copy it.

3. Save the signing secret

In the connection’s settings, paste the secret into the Signing Secret field and save. Inbound deliveries are verified with HMAC-SHA256 against the X-PagerDuty-Signature header; deliveries with no/invalid signature are rejected.

To verify the wiring without firing a real incident, use PagerDuty’s Send Test Event button on the subscription. The test event arrives as a pagey.ping and lands in pagerduty/events/pagey.ping.

Description Field

Document the services, escalation policies, and tag conventions that agents should know about:

Production PagerDuty.

Common queries:
- Active incidents → GET /incidents?statuses[]=triggered&statuses[]=acknowledged
- On-call for a schedule → GET /oncalls?schedule_ids[]=PXXXXXX
- Service by name → GET /services?query=<service-name>

Conventions:
- Incident urgency=high → page on-call
- Incident urgency=low → email-only, no page

Best Practices

• Prefer read-only API keys for agents that only need to look up incidents and on-call info
• Use a service-account user, not a personal user, so the API key survives personnel changes
• Rotate tokens periodically — PagerDuty supports multiple keys, so you can issue a new one before revoking the old