PagerDuty

Trigger PagerDuty incidents via Events API v2 with dedup_key = Yorker incident ID, observations and scoped hypothesis in custom_details.

PagerDuty

Yorker drives PagerDuty through the Events API v2. One Yorker incident maps to one PagerDuty alert; the dedup_key is the Yorker incident_id. Subsequent lifecycle events update the same PagerDuty alert rather than creating new ones.

For the underlying model (lifecycle states, event types, scoped hypothesis), see Incidents.

Set up

In PagerDuty, add an Events API v2 integration to the service that should receive Yorker alerts. Copy the Integration Key (also called the routing key).
Note your PagerDuty region: us for events.pagerduty.com, eu for events.eu.pagerduty.com.
In Yorker, create a notification channel of type pagerduty with the routing key and region:

curl -X POST https://yorkermonitoring.com/api/notification-channels \
  -H "Authorization: Bearer $YORKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pd-oncall",
    "channel": {
      "type": "pagerduty",
      "routingKey": "R0UTINGKEY1234567890ABCDEF",
      "serviceRegion": "us"
    }
  }'

Field	Required	Default	Description
`routingKey`	yes	—	Events API v2 integration key
`serviceRegion`	no	`us`	`us` or `eu`

Event mapping

Yorker event	PD `event_action`	Notes
`opened`	`trigger`	First alert created
`acknowledged`	`acknowledge`	Forwards the Yorker ack to PD
`auto_resolved`	`resolve`	After cool-down elapses
`closed`	`resolve`	User-initiated close
`reopened`	`trigger`	Recurrence re-triggers the alert
`note_added`	`trigger`	PD treats duplicate dedup_key triggers as updates
`severity_changed`	(skipped)	Events API v2 has no matching action
`alert_attached`	(skipped)	Internal-only

dedup_key is always the Yorker incident_id. severity maps critical → critical, warning → warning, info → info.

Example opened payload:

{
  "routing_key": "R0UTINGKEY…",
  "event_action": "trigger",
  "dedup_key": "inc_abc",
  "payload": {
    "summary": "[Yorker] Checkout API outage",
    "source": "yorker",
    "severity": "critical",
    "class": "synthetic-monitoring",
    "custom_details": {
      "incident_id": "inc_abc",
      "event_type": "opened",
      "event_id": "ievt_001",
      "sources": ["synthetic_http"],
      "affected_checks": ["Checkout API"],
      "locations_affected": ["loc_us_east_1", "loc_eu_west_1"],
      "shared_failing_domains": ["api.stripe.com"],
      "hypothesis": {
        "summary": "Stripe API is returning 503/504; checkout is blocked.",
        "confidence": 0.75,
        "ruled_in": ["shared_failing_domain=api.stripe.com"],
        "ruled_out": ["DNS resolution: NXDOMAIN not observed", "TLS: handshake completes"],
        "scope": "external_symptoms_only",
        "correlation_dimensions_matched": ["shared_failing_domain", "error_pattern"]
      },
      "actor": { "type": "system", "id": null }
    }
  },
  "links": [
    { "href": "https://yorkermonitoring.com/dashboard/incidents/inc_abc", "text": "View in Yorker" }
  ]
}

When the incident is a recurrence of prior closed incidents, Yorker adds up to 5 prior incident links to the links array so the on-call engineer can pivot to history without leaving PD.

Template overrides

Only the custom_details block is user-editable. The envelope (routing key, event action, dedup key, severity, source, summary) is fixed so dedupe and severity semantics stay consistent across your tenants.

curl -X PUT https://yorkermonitoring.com/api/notification-channels/nch_abc \
  -H "Authorization: Bearer $YORKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "incidentTemplate": {
      "channelType": "pagerduty",
      "overrides": {
        "opened": {
          "customDetails": "{\"runbook\":\"https://wiki.acme.com/runbooks/checkout\",\"yorker_link\":\"{{incident.triageUrl}}\",\"severity\":\"{{incident.severity}}\",\"hypothesis\":\"{{payload.hypothesis.summary}}\"}"
        }
      }
    }
  }'

The rendered string must parse as a JSON object. On render failure or invalid JSON the default custom_details block is used instead; dispatch does not fail.

Helper and render context are the same as the Slack integration.

Ack propagation

Acknowledging in Yorker sends event_action: "acknowledge" to PagerDuty. Acknowledging in PagerDuty does not propagate back to Yorker in this release — bidirectional sync is tracked as a future enhancement.

Disabling

The PagerDuty channel type is incident-pipeline-only — it has no legacy per-alert dispatch path. incidentSubscribed is locked to true for PagerDuty channels; the API rejects create/update requests that set it to false. To stop routing incidents to a PagerDuty channel, delete it or remove it from the alert rule's channel list.

Slack ServiceNow