PagerDuty Provider

PagerDuty is a cloud-hosted incident management platform. No Docker setup is required — configure it directly in Admin Panel → Incidents → Providers using your PagerDuty account credentials.

---

What You Get

• Inbound webhook: PagerDuty v3 webhooks received and normalized in real time
• Outbound API: agents can list, trigger, acknowledge, and resolve PagerDuty incidents via MCP tools
• HMAC-SHA256 webhook signature verification (X-PagerDuty-Signature)

---

Step 1 — Create a PagerDuty API Token

1. Log in to PagerDuty.
2. Go to Integrations → API Access Keys.
3. Click Create New API Key with a descriptive name (e.g. hrida-ai-studio).
4. Copy the token — you only see it once.

---

Step 2 — Create an Events API v2 Integration (for agent-created incidents)

This is required if you want agents to create PagerDuty incidents, not just receive them.

1. Go to a Service in PagerDuty.
2. Click Integrations → Add Integration → select Events API v2.
3. Click Add — copy the Integration Key (also called Routing Key).

---

Step 3 — Configure the Provider in hrida-ai-studio

1. Go to Admin Panel → Incidents → Providers.
2. Click + Add Provider → select PagerDuty.
3. Fill in:

Field	Value
Name	e.g. PagerDuty Engineering
REST API Token	The token from Step 1
Events Routing Key	The Integration Key from Step 2
Webhook Secret	A random string you'll also enter in PagerDuty (see Step 4)

4. Click Save — copy the Webhook URL from the card.

---

Step 4 — Configure the Outgoing Webhook in PagerDuty

1. In PagerDuty, go to Integrations → Generic Webhooks (V3).
2. Click New Webhook.
3. Set:

Field	Value
Webhook URL	The URL from the provider card
Scope type	Account (or Service/Team for narrower scope)
Event subscription	incident.triggered, incident.acknowledged, incident.resolved
Secret	The same Webhook Secret you entered in hrida-ai-studio

4. Save. PagerDuty will sign every outgoing webhook with X-PagerDuty-Signature: v1=<hmac-sha256-hex>.

---

Webhook Authentication

PagerDuty uses HMAC-SHA256 to sign the raw request body. The signature is sent in:

X-PagerDuty-Signature: v1=<hex>

hrida-ai-studio verifies each delivery. The header may contain multiple comma-separated signatures for key rotation — all are checked.

Keep your webhook secret private

The webhook secret must match between PagerDuty and your hrida-ai-studio provider config. Rotate it in both places if it's ever compromised.

---

Incident State Mapping

PagerDuty event type	Canonical state in hrida-ai-studio
incident.triggered	firing
incident.acknowledged	acknowledged
incident.resolved	resolved
incident.annotated	acknowledged

---

Severity Mapping

PagerDuty urgency values are mapped to a normalized severity:

PagerDuty urgency	Canonical severity
critical / high	critical / high
warning	warning
info / low	info
unknown / missing	warning (default)

---

Agent Tools (via hrida-mcpo)

Run an hrida-mcpo instance pointed at PagerDuty's OpenAPI spec, then add it as a tool server:

# docker-compose.override.yml
hrida-mcpo-pagerduty:
  image: ghcr.io/hrida-ai/hrida-mcpo:latest
  ports:
    - "8092:8000"
  environment:
    OPENAPI_SPEC_URL: https://api.pagerduty.com/openapi.json
    API_BASE_URL: https://api.pagerduty.com
    AUTH_HEADER: Authorization
    AUTH_TOKEN: "Token token=<your_api_token>"
    SERVER_NAME: pagerduty-incidents
  networks:
    - openhridaai-network

Add http://localhost:8092 as a tool server in Admin Panel → Settings → Tool Servers.

Key tools available: list_incidents, get_incident, update_incident, create_incident, list_services, list_schedules, list_users.

---

Workflow Trigger Integration

See the Incident Management overview for details on triggering agent workflows when PagerDuty incidents change state.

---

Troubleshooting

Webhook delivers 401 → The webhook_secret in your hrida-ai-studio provider config doesn't match what you entered in PagerDuty's webhook configuration. Both must be identical.

Incidents not appearing in the panel → Check that the event subscriptions in PagerDuty include incident.triggered, incident.acknowledged, and incident.resolved.

create_incident fails with "routing_key not configured" → The Events Routing Key field was left empty in the provider config. Add it by editing the provider in Admin Panel → Incidents → Providers.

HMAC verification failing → PagerDuty sends the signature over the raw (unmodified) request body. Make sure no proxy or middleware is modifying the body before it reaches hrida-ai-studio.