PagerDuty ExecModule

Overview

PagerDutyModule connects ValkyrAI workflows to PagerDuty REST API v2 through the native map I/O ExecModule ABI. Workflow Studio discovers it as PagerDutyModule. REST API keys and scoped OAuth tokens resolve only from a bound READY IntegrationAccount; workflow input cannot provide credentials or redirect requests to arbitrary hosts.

The first production operation set focuses on incident detection, triage, accountable mutation, and evidence:

• discovery: list_services, list_escalation_policies, list_priorities, list_oncalls;
• incidents: list_incidents, get_incident, create_incident, update_incident;
• evidence: add_incident_note, list_incident_notes, list_incident_log_entries;
• identity: get_user.

This surface follows the incident, incident-note, log-entry, and user resources in n8n's PagerDuty node, then adds governed discovery operations useful to agents. List operations use bounded offset pagination. Provider responses and errors are size-limited and redacted. Only GET requests retry automatically; writes run once because their outcome can be ambiguous after a timeout.

Usage

1. Create a dedicated PagerDuty REST API key or scoped OAuth app for the automation identity.
2. Grant only the incident, service, escalation-policy, priority, on-call, log-entry, and user access the workflow needs.
3. Store the token in the encrypted apiKey field of an IntegrationAccount and set the account status to READY.
4. Put the requester's PagerDuty email in IntegrationAccount.username or accountId, or supply requesterEmail explicitly for a write.
5. Bind the account through ExecModuleConfig.authConfig.integrationAccount.
6. Discover IDs with list operations before creating or updating an incident.

Inputs

Name	Type	Requirement	Default	Description and constraints
operation	string	Required	None	One of the twelve operations above.
authMode	string	Optional	api_token	api_token sends Token token=…; oauth2 sends Bearer ….
region	string	Optional	us	us or eu; selects a fixed PagerDuty API origin.
incidentId	string	Incident, note, or incident-log operations	None	PagerDuty ID, 1–64 letters, digits, _, or -.
serviceId	string	create_incident; optional list filter array uses serviceIds	None	Valid bounded PagerDuty ID.
userId	string	get_user	None	Valid bounded PagerDuty ID.
requesterEmail	string	Write operations	Account identity	Valid email used in PagerDuty's From header.
title	string	create_incident; optional update	None	1–1,024 characters.
statusValue	string	Optional update	None	triggered, acknowledged, or resolved.
urgency	string	Optional create/update/filter	None	high or low.
details	string	Optional create/update	None	Incident body, maximum 20,000 characters.
resolution	string	Optional update	None	Resolution summary, maximum 10,000 characters.
incidentKey	string	Optional create	None	Caller-owned correlation key, maximum 255 characters.
escalationPolicyId	string	Optional create/update	None	Valid escalation-policy ID.
priorityId	string	Optional create/update	None	Valid priority ID.
note	string	add_incident_note	None	1–10,000 characters.
incident	object or JSON string	Optional create/update	None	Allowlisted incident fields only; 256 KiB cap.
statuses	array or JSON string	Optional incident list	None	Up to three supported statuses.
serviceIds, teamIds, userIds	arrays or JSON strings	Optional list filters	None	Up to 100 valid PagerDuty IDs per filter.
since, until	strings	Optional list filters	None	Provider-compatible time filters, maximum 64 characters.
offset	integer	Optional list continuation	0	Starting offset from 0 through 1,000,000.
limit	integer	Optional	100	Maximum returned resources, 1–10,000.
returnAll	boolean	Optional	false	Follow offset pages to exhaustion or the 10,000-item cap.
requestId	string	Optional	None	Caller correlation value sent as X-Request-Id, maximum 128 characters.

Typed inputs override matching allowlisted fields. Create accepts type, title, service, urgency, body, escalation_policy, priority, and incident_key; required title and serviceId are always rebuilt from validated inputs. Update accepts type, title, status, urgency, body, escalation_policy, priority, assignments, and resolution. Reference objects must contain only validated id and type fields.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
attempts	integer	Always	Total provider attempts across pages.
httpStatus	integer	Provider responded	Last PagerDuty HTTP status.
data	object	Single-resource/mutation success	Provider incident, note, or user.
id, providerStatus, incident_number	string	Provider returns field	Safe convenience fields; providerStatus never replaces the module success state.
items / count	array / integer	List success	Bounded provider resources and emitted count.
hasMore / nextOffset	boolean / integer	List success	Provider continuation state.
requestId	string	Provider supplies one	Safe provider trace reference.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Tokens and authorization headers never enter outputs. Provider messages pass through ValkyrAI's shared workflow sensitive-data policy.

IntegrationAccount Requirements

Setting	Requirement
Provider	PagerDuty REST API v2
Authentication	REST API key (Token token=…) or scoped OAuth (Bearer …)
accountName	Human-readable automation identity
username or accountId	PagerDuty requester email used for writes, unless supplied per call
apiKey	Preferred encrypted SecureField containing the token
password	Encrypted fallback only; prefer apiKey
status	Must be READY

Use the least-privilege token that can read the discovery/evidence resources and mutate incidents only when the workflow requires writes. Read-only PagerDuty keys cannot create incidents, add notes, acknowledge, or resolve incidents. OAuth refresh and token rotation belong to the platform IntegrationAccount lifecycle, never workflow inputs.

Configuration

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:pagerduty-incident-automation"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": false
  },
  "executionConfig": {"timeoutMs": 30000},
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_incidents\",\"statuses\":[\"triggered\",\"acknowledged\"],\"urgency\":\"high\",\"limit\":100}"
  }
}

The integration-account value is symbolic. Persisted workflows use the generated relationship and never a plaintext token.

Operations

Operation	PagerDuty behavior	Side effect
list_services	Lists services visible to the token.	Read-only; safe retries.
list_escalation_policies	Lists available escalation policies.	Read-only; safe retries.
list_priorities	Lists configured incident priorities.	Read-only; safe retries.
list_oncalls	Lists current on-call entries with bounded filters.	Read-only; safe retries.
list_incidents	Lists incidents with bounded status, urgency, identity, service, and time filters.	Read-only; safe retries.
get_incident	Reads one incident.	Read-only; safe retries.
create_incident	Creates one incident for a validated service and requester.	New incident; single attempt.
update_incident	Updates allowlisted incident state, assignment, urgency, references, or resolution.	Audit mutation; single attempt.
add_incident_note	Adds one bounded note to an incident.	New evidence record; single attempt.
list_incident_notes	Lists incident notes.	Read-only; safe retries.
list_incident_log_entries	Lists incident log evidence.	Read-only; safe retries.
get_user	Reads one PagerDuty user.	Read-only; safe retries.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/invalid account, email, ID, filter, JSON, reference, or incident mutation.	No	Correct input; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No bound account.	No	Bind a PagerDuty IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account is not READY.	No	Repair or reconnect the account.
PAGERDUTY_HTTP_400	Provider rejected a filter, header, or payload.	No	Correct the bounded request.
PAGERDUTY_HTTP_401 / 403	Token invalid, expired, read-only, or missing access.	No	Rotate the token or grant minimum access.
PAGERDUTY_HTTP_404	Resource is absent or invisible.	No	Re-run discovery with the same account.
PAGERDUTY_HTTP_429 / 5xx	Rate limit or transient provider failure.	Yes for reads	Honor provider timing; reconcile writes before retrying.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure.	Yes for reads	Verify connectivity; inspect PagerDuty state before repeating a write.
RESPONSE_TOO_LARGE	Response exceeded 5 MiB.	No	Narrow filters or lower the limit.
INVALID_PROVIDER_RESPONSE	Expected resource wrapper is absent or pagination is contradictory.	No	Use requestId and verify API compatibility.

Example

Acknowledge a verified incident after an automated triage workflow identifies the active service owner:

{
  "operation": "update_incident",
  "incidentId": "P123ABC",
  "statusValue": "acknowledged",
  "requesterEmail": "ops@example.com",
  "requestId": "api-0-triage-20260810"
}

Expected result:

{
  "status": "success",
  "operation": "update_incident",
  "attempts": 1,
  "httpStatus": 200,
  "id": "P123ABC",
  "data": {
    "id": "P123ABC",
    "incident_number": 1842,
    "status": "acknowledged"
  }
}

Notes

• Pagination: PagerDuty lists use offset, limit, and more. Pages request at most 100 items and total output never exceeds 10,000. An empty page with more: true fails closed.
• Rate limits: reads retry HTTP 408, 429, 500, 502, 503, and 504 according to RetryPolicy, honoring Retry-After and PagerDuty's ratelimit-reset delay. Writes never retry automatically.
• API limits: provider responses are capped at 5 MiB, structured incident bodies at 256 KiB, ID filter arrays at 100 entries, and text fields at their documented module bounds. Provider account limits still apply.
• Idempotency: creates, incident updates, and notes are single-attempt. Use incidentKey and requestId; reconcile the incident or log entries before repeating any request whose response was lost.
• Destructive behavior: this release exposes no deletion. Resolving an incident is an audited state change and requires an explicit update_incident; it is not treated as a read retry.
• Security: credentials remain in IntegrationAccount SecureFields. Fixed regional hosts, encoded path segments, allowlisted payloads, explicit requester identity, bounded responses, and redacted errors prevent arbitrary routing or token reflection.
• External verification: request construction, pagination, validation, retry safety, redaction, payload mapping, and metadata discovery are deterministic local tests. Live PagerDuty roles, scopes, schedules, escalation, account features, and incident behavior require separately authorized provider credentials and are not exercised in repository tests.
• Deferred operations: schedules, teams, maintenance windows, alert grouping, event ingestion, response plays/workflows, analytics, status dashboards, webhooks/triggers, OAuth refresh, and arbitrary raw requests.
• Functional references: n8n PagerDuty node source, PagerDuty API access keys, and PagerDuty REST API rate limits.