Connecting PagerDuty to Landfall
PagerDuty connects in two independent directions, and each is useful on its own:
- On-call — Landfall reads who is on shift right now, so the war room knows who to involve. One read-only API token.
- Trigger — a PagerDuty incident opens a Landfall war room the moment it fires. One webhook subscription.
What you'll need
- A PagerDuty account with permission to create API keys and webhook subscriptions.
- Your Landfall organization's slug — it appears in your Landfall URL, e.g. /o/acme/….
- An admin on your Landfall organization.
Both live under PagerDuty's Integrations menu, in the Developer Tools column.
1. On-call — who is on shift
Landfall calls exactly one PagerDuty endpoint for this: GET /oncalls. It never creates, modifies, or resolves anything in PagerDuty. Give it a token scoped to match.
Integrations → API Access Keys → Create New API Key
Name it something you'll recognise later, e.g. landfall-oncall-read, and tick "Read-only API Key". Landfall only reads, so a read/write key grants more than it will ever use.
yourcompany.pagerduty.com/api_keys
Read-only is the correct choice here, not a precaution. Copy the key — it is shown once
PagerDuty displays the value a single time. If you lose it, delete the key and create another; there is no way to reveal it again.
yourcompany.pagerduty.com/api_keys
Paste it into Landfall
Settings → Integrations → PagerDuty, into REST API token. Save, and Landfall verifies it against PagerDuty's /abilities endpoint before storing anything — a token that cannot authenticate is refused rather than saved.
Connecting the token lets Landfall resolve the current roster and draft a page. It does not send anything. Real outbound paging is off by default — the shipped adapter is a dry run that records what it would have sent — and turning it on is a separate, admin-only, per-organization decision. Every page is also approval-gated: an agent drafts, a human approves, and only then does it send.
2. Trigger — PagerDuty opens a war room
A PagerDuty webhook v3 subscription posts to Landfall, and every delivery is verified against a signing secret PagerDuty issues when you create the subscription.
Integrations → Generic Webhooks (v3) → New Webhook
yourcompany.pagerduty.com/integrations/webhooks
Fill in the subscription
Webhook URL https://api.landfalls.ai/triggers/pagerduty/<your-org-slug> Scope type Account for every service, or Service to limit it to one. Event subscription incident.triggered · incident.escalated · incident.resolved Deselect everything else. Landfall understands exactly those three and answers 200 to the rest, so subscribing to all of them costs you delivery volume and buys nothing.
yourcompany.pagerduty.com/integrations/webhooks/add
The slug in the URL is not a credentialIt selects which organization's signing secret the delivery is checked against, and nothing more. An unknown slug and a valid slug with a bad signature return the identical refusal, so the endpoint cannot be used to discover which organizations exist.
Copy the signing secret — also shown once
On save, PagerDuty shows a signing secret. Paste it into Settings → Integrations → PagerDuty → Webhook v3 signing secret in Landfall.
Until that secret is stored, every delivery for your organization is refused. That is deliberate: it is what turns the endpoint on, so there is no separate switch that could be on while the secret is missing.
Test it with a real incident
In PagerDuty, New Incident against any service the subscription covers. A Landfall war room should open within seconds.
yourcompany.pagerduty.com/incidents/create
What each event does
| PagerDuty event | In Landfall |
|---|---|
| incident.triggered | Opens a war room — or, if that PagerDuty incident already has one, attaches to it rather than opening a second. |
| incident.escalated | Appends pagerduty.escalated to the existing timeline. |
| incident.resolved | Appends pagerduty.resolved. It does not close the war room. |
PagerDuty resolving its own incident is a fact about PagerDuty, not a decision about yours. Landfall records it on the timeline and leaves the room open — a human still closes it, after the investigation and postmortem are actually done. If closing the page also closed the room, the record would end at the moment the alarm stopped rather than the moment you understood it.
Troubleshooting
| Symptom | Cause |
|---|---|
| No war room appears | Check the subscription is active and that the signing secret is saved in Landfall. PagerDuty retries failures with backoff and eventually disables a subscription that keeps failing. |
| Deliveries refused | The secret in Landfall doesn't match the subscription's. Secrets are issued per subscription — recreating the webhook issues a new one. |
| Wrong organization | The slug in the webhook URL doesn't match your Landfall organization. |
| On-call shows nobody | Landfall reports an empty roster honestly rather than inventing a responder. Check the escalation policy actually has someone on call right now. |
What Landfall does with the connection
- Reads only. The on-call token is used for GET /oncalls. Nothing in Landfall writes to PagerDuty.
- Every delivery is verified. Inbound webhooks are checked against the signing secret before anything is created, and an unverified delivery is refused identically to an unknown one.
- Per organization. Both credentials belong to your Landfall organization alone and are resolved per request.
- Revocable from your side. Delete the API key or the webhook subscription in PagerDuty and access ends immediately.