PagerDuty setup

Step 1 — Create the service in PagerDuty

In PagerDuty, go to Services → New Service. Name it something legible ("Mesedi — Production Agents" is a good pattern) and assign the escalation policy that should page for these incidents. If you route all agent failures to the same on-call rotation you already have for API 5xxs, use that policy.

Step 2 — Add an Events API v2 integration

Inside your new service, open the Integrations tab, click Add an integration, and pick Events API v2 from the vendor list (search box: "events api"). Give it a name — "Mesedi" is fine — and save.

PagerDuty will show you an Integration Key — a 32-character alphanumeric string. This is the routing_keyin the payload Mesedi will send. Copy it. You'll paste it into Mesedi in Step 4.

Step 3 — Choose your endpoint region

PagerDuty publishes two regional endpoints for the Events API v2:

• US: https://events.pagerduty.com/v2/enqueue
• EU: https://events.eu.pagerduty.com/v2/enqueue

Match the region of your PagerDuty account. If your account was created under "PagerDuty EU" use the EU URL; otherwise use US. Either URL works — Mesedi's adapter recognizes both and reshapes the payload identically.

Step 4 — Create the webhook in Mesedi

On the Mesedi dashboard, go to Webhooks and click + Add webhook. Fill in:

• URL: the regional endpoint from Step 3.
• PagerDuty integration key: paste the 32-char key from Step 2. This field only appears once the URL is recognized as PagerDuty.
• Name (optional): something like "PagerDuty — Prod Agents" so it's legible in the webhook list.
• Severity filter: most teams pick criticalonly — you don't want warning-level events waking the on-call.
• Notify on recurrences: off is the recommended default for PagerDuty. New failure groups create incidents; recurrences flow into existing incidents via dedup_key (see the next section) without generating new pages.

Save. Then click Test on the new row to fire a synthetic delivery. You should see the test event land in PagerDuty as an info-severity incident that resolves itself immediately — test deliveries are pinned to info severity so setup pings never page the on-call engineer.

How recurrences look in PagerDuty

Each Mesedi failure group has a stable dedup_key of {project_id}:{group_id}. PagerDuty uses this to route recurrences into the same incident: the first failure_group.created event opens the incident; subsequent failure_group.recurred events (if you enabled recurrences on the webhook) update the same one without creating a new page.

The incident stays open until you resolve it in PagerDuty. Mesedi does not currently emit event_action=resolve; that's intentional — only a human should decide when a failure class is truly fixed, and detector recovery signals are not always reliable enough to auto-close an incident.

Severity mapping

Mesedi's three severity levels map 1:1 to PagerDuty:

• critical → PagerDuty critical (pages per your escalation policy)
• warning → PagerDuty warning (ticket-style incident, does not page unless the policy says so)
• info → PagerDuty info (log-only unless the policy escalates it)

Change the per-class severity mapping under Settings → Severity Routing on the Mesedi side. Anything unrecognized maps defensively to info so a stale seed value never 400s the PagerDuty API.

Troubleshooting

• "Invalid routing_key" in the delivery log — you pasted a wrong string into the PagerDuty integration key field. The correct value is the 32-char Integration Key on the service's Integrations tab, NOT your API key or user auth token.
• Incidents never open despite webhooks reporting 202 — check your service's severity filter. If Mesedi is sending info-severity events but your PagerDuty escalation policy ignores info, the incident is being filtered by PagerDuty, not dropped by us.
• Recurrences opening new incidents instead of updating the existing one — this is almost always a wrong dedup_key on the receiver side. Mesedi builds dedup_key from {project_id}:{group_id}; if you fork the same failure across two projects they will surface as separate incidents (correct behavior).