PagerDuty & Opsgenie

If your team already runs on-call in PagerDuty or Opsgenie, connect it to SutramX. A monitor going down triggers a page, acknowledging in SutramX acknowledges it there, and the recovery resolves it, with no manual clean-up.

PagerDuty and Opsgenie depend on your plan. See Plans & limits. Only the workspace owner can connect, edit or remove them.

How the sync works#

Each SutramX incident maps to exactly one PagerDuty incident or Opsgenie alert. SutramX uses the incident ID as PagerDuty's dedup_key and sutramx-<incident id> as Opsgenie's alias, so repeated sends land on the same page instead of opening new ones.

A few rules make sure pages never get stuck open:

• Recoveries ignore the connection's routing. If a page was opened, it is resolved even if you changed the routing since.
• An acknowledgement is only sent if a down alert went out for the incident.
• Paging tools receive incidents only. SSL, domain, maintenance and other notices never page anyone.

The sync is one-way. Acknowledging or resolving in PagerDuty or Opsgenie doesn't change the incident in SutramX.

PagerDuty#

Connect with PagerDuty (one click)#

If the PagerDuty card shows Connect with PagerDuty:

1. Click Connect with PagerDuty.
2. Sign in to PagerDuty and approve access.
3. Pick the service that should receive SutramX incidents (Choose a PagerDuty service). If your account has only one service, it is chosen automatically.
4. Click Connect.

SutramX adds an Events API v2 integration called "SutramX" to that service for you. EU-hosted PagerDuty accounts are detected automatically. The connection is named after the service, for example "PagerDuty · Checkout".

Connect with an integration key#

If the card shows Connect PagerDuty, or you choose Enter an integration key manually:

1. In PagerDuty, go to Services, open your service, then Integrations → Add integration, and choose Events API V2.
2. Copy the Integration Key.
3. In SutramX, paste it into Integration (routing) key and click Connect.

What PagerDuty receives#

A trigger event looks like this:

{
  "routing_key": "<your integration key>",
  "event_action": "trigger",
  "dedup_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "payload": {
    "summary": "Checkout API is DOWN",
    "source": "https://api.example.com/health",
    "severity": "critical",
    "timestamp": "2026-10-02T09:14:03.120Z",
    "component": "sutramx-monitor",
    "custom_details": {
      "monitor_name": "Checkout API",
      "monitor_url": "https://api.example.com/health",
      "region": "FRA1 (Frankfurt, Germany)",
      "reason": "<failure reason>",
      "explanation": "Down from 2 of 3 regions: HTTP 503 server error (Arizona still up)"
    }
  }
}

explanation is the incident's one-line verdict (see Why this alert & flakiness score); it is left out when no verdict is available. The recovery is a resolve event with the same dedup_key, and an acknowledgement is an acknowledge event with the same dedup_key. Every incident is sent with severity critical.

Opsgenie#

Connect Opsgenie#

1. In Opsgenie, go to Settings → Integrations → Add integration and choose API.
2. Keep Create and Update Access enabled. Read access isn't needed.
3. Copy the API key.
4. In SutramX, click Connect Opsgenie on the Opsgenie card.
5. Paste the key into API key, choose the Region, and click Connect.

What Opsgenie receives#

{
  "message": "Checkout API is DOWN",
  "alias": "sutramx-7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "description": "[DOWN] Checkout API is DOWN\nURL: https://api.example.com/health\nRegion: FRA1 (Frankfurt, Germany)\nDetail: <failure reason>\nWhy: Down from 2 of 3 regions: HTTP 503 server error (Arizona still up)\nDetails: https://app.sutramx.com/dashboard/incidents/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "source": "SutramX",
  "priority": "P1",
  "details": {
    "monitor_name": "Checkout API",
    "monitor_url": "https://api.example.com/health",
    "region": "FRA1 (Frankfurt, Germany)",
    "incident_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }
}

The message is cut to Opsgenie's 130-character limit; the full text is in description. Every alert is created with priority P1. Recovery closes the alert by alias with the note "Monitor recovered", and an acknowledgement adds the note "Acknowledged in SutramX by <name>" (or "Acknowledged in SutramX" when no name is known).

Test the connection#

Tests create real pages, so they never run automatically. Open the connection's menu and choose Send test, then confirm.

• PagerDuty: triggers a real incident (paging whoever is on call for the service) and resolves it immediately.
• Opsgenie: creates a test alert (which may notify whoever is on call) and closes it a few seconds later.

If the close step fails, the result says so and you should close the test alert yourself in Opsgenie.

Routing and multiple services#

You can connect up to 10 PagerDuty and 10 Opsgenie connections, for example one PagerDuty service per team. To control which monitors page which service, open the connection's menu, choose Routing, pick All monitors, Selected groups or Selected monitors, and click Save routing.

Escalation steps that target PagerDuty or Opsgenie go to every connection of that tool, regardless of routing.

Using PagerDuty with escalation policies#

You can use PagerDuty or Opsgenie as a step in a SutramX escalation policy, for example: email the on-call engineer first, then page PagerDuty if nobody acknowledges within 10 minutes.

PagerDuty also acts as a safety net for email steps. If an email step can't be delivered (nobody is on call, the recipient hasn't confirmed alert emails, or the email fails), SutramX triggers your first PagerDuty connection instead, with a summary like "Checkout API incident escalation step 2".

Troubleshooting#

• "PagerDuty responded 400": the integration key is wrong or isn't an Events API v2 key. Copy it again from the service's Events API V2 integration.
• "OpsGenie responded 401" or "403": the API key is wrong, deleted, or lacks create and update access. Check the region too.
• Pages open but never resolve: check the incident's Notifications list in SutramX for the recovery delivery and its error.
• No acknowledgement in PagerDuty: acknowledgements are only sent when a down alert went out for the incident, and only for the first acknowledgement of an incident.
• Connection shows Failing: the last 3 deliveries failed. Fix the key with Edit, then send a test.