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_key in 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 critical only: 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).