PagerDuty Integration#

Connect APIAssert to PagerDuty for on-call alerting. When monitors fail, APIAssert automatically creates PagerDuty incidents that route to the right team member.

Why PagerDuty?#

• On-call rotation — alerts go to whoever is on-call
• Escalation policies — automatic escalation if not acknowledged
• Incident management — track and resolve issues systematically
• Mobile alerts — push notifications, SMS, phone calls

What You'll Get#

• Automatic incident creation when monitors fail
• Auto-resolve when monitors recover
• Rich context — monitor details, response data, failure reasons
• Deduplication — prevent alert storms

Setup Guide#

Step 1: Create Integration in PagerDuty#

1. Log in to PagerDuty
2. Go to Services → Select your service (or create one)
3. Click Integrations → Add an integration
4. Search for "Events API v2" and add it
5. Copy the Integration Key

Step 2: Add PagerDuty in APIAssert#

1. Go to Alerts → Channels in your APIAssert dashboard
2. Click Add Channel → PagerDuty
3. Paste your integration key
4. Give the channel a name (e.g., "PagerDuty - Production")
5. Click Save

Step 3: Test the Integration#

Click Send Test to trigger a test incident in PagerDuty. Resolve it after confirming it appeared.

Step 4: Assign to Monitors#

Edit your monitors and add the PagerDuty channel under Alert Channels.

How It Works#

Incident Creation#

When a monitor fails, APIAssert sends a trigger event to PagerDuty:

{
  "routing_key": "your-integration-key",
  "event_action": "trigger",
  "dedup_key": "pingpost-mon_abc123",
  "payload": {
    "summary": "Monitor Failed: Production API",
    "severity": "critical",
    "source": "APIAssert",
    "custom_details": {
      "monitor": "Production API",
      "url": "https://api.example.com/health",
      "status_code": 500,
      "response_time": "2,340ms",
      "region": "US East",
      "failure_reason": "$.status expected 'success', got 'error'"
    }
  }
}

Auto-Resolution#

When the monitor recovers, APIAssert sends a resolve event:

{
  "routing_key": "your-integration-key",
  "event_action": "resolve",
  "dedup_key": "pingpost-mon_abc123"
}

The incident is automatically resolved in PagerDuty.

Configuration Options#

Severity Mapping#

Configure severity based on monitor type:

Best Practices#

Create Dedicated Services#

Set up separate PagerDuty services:

• API Production — Critical production monitors
• API Staging — Non-critical, business hours only
• Third-party Dependencies — External services you depend on

Configure Escalation Policies#

Set up escalation for critical monitors:

1. Level 1: On-call engineer (immediate)
2. Level 2: Team lead (after 15 minutes)
3. Level 3: Engineering manager (after 30 minutes)

Use Business Hours#

For non-critical monitors, configure PagerDuty to only alert during business hours:

1. Go to Service → Support Hours
2. Set active hours (e.g., Mon-Fri 9am-6pm)
3. Queue alerts outside these hours

Combine with Slack#

Use PagerDuty for on-call, Slack for team visibility:

Production failure:
├── PagerDuty → On-call engineer (immediate)
└── Slack #incidents → Team visibility

Troubleshooting#

Incidents not creating?

• Verify the integration key is correct
• Check that the PagerDuty service is enabled
• Ensure your PagerDuty account is active

Too many incidents?

• Enable deduplication in PagerDuty
• Increase monitor check intervals
• Use APIAssert's alert cooldown feature

Incidents not auto-resolving?

• Verify "Auto-resolve" is enabled in APIAssert
• Check that dedup_key matches between trigger and resolve

Alert fatigue?

• Set appropriate severity levels
• Configure snooze/maintenance windows
• Use escalation policies instead of direct alerts

Advanced: Custom Event Rules#

Create PagerDuty event rules to transform incoming alerts:

1. Go to Event Rules in PagerDuty
2. Add a rule matching source "APIAssert"
3. Configure actions (add notes, change severity, route to service)

Example rule:

IF source contains "APIAssert"
AND custom_details.region contains "staging"
THEN set severity to "warning"
AND route to "API Staging" service

Next Steps#

• Set up Slack for team visibility
• Configure Opsgenie as backup
• Learn about response validation