PagerDuty API Compatibility

Overview

Migrating from PagerDuty to Sizemotion? Our PagerDuty-compatible endpoint allows you to switch incident management platforms without reconfiguring your monitoring tools. Send the same event payloads you use today—just change the endpoint URL and authentication.

Migration Guide

Switching from PagerDuty requires only two changes to your existing configuration:

POST https://events.pagerduty.com/v2/enqueue
Authorization: Token token=abc123...

POST https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5
Authorization: Bearer xyz789...

Setup Steps

Step 1: Get Your Webhook URL

Each team has a unique PagerDuty-compatible webhook URL:

1. Navigate to Team Settings in your workspace
2. Locate the Team Information section
3. Note your Team ID (e.g., 5)
4. Your webhook URL format:

   https://sizemotion.com/api/v1/incidents/webhook/pagerduty/{TEAM_ID}

Step 2: Create API Token

1. Go to Admin Settings → API Tokens
2. Click Create New Token
3. Name it descriptively (e.g., "PagerDuty Migration - Production")
4. Save the token securely - it won't be shown again!

Step 3: Update Your Monitoring Tools

Update your existing alert configurations with the new endpoint:

Datadog Integration

1. Go to Integrations → PagerDuty
2. Edit your existing PagerDuty service
3. Update service API URL to: https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5
4. Update integration key (use your Sizemotion API token as Bearer token)
5. Keep your existing alert format

Prometheus AlertManager

Update your alertmanager.yml:

receivers:
  - name: 'sizemotion-pagerduty'
    webhook_configs:
      - url: 'https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5'
        http_config:
          authorization:
            credentials: 'YOUR_API_TOKEN'
        send_resolved: false

Custom Scripts

Update your monitoring scripts with new values:

PAGERDUTY_ENDPOINT="https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5"
PAGERDUTY_API_KEY="Bearer YOUR_API_TOKEN"

Step 4: Test the Integration

Verify your setup:

1. Send a test event from your monitoring tool
2. Check your Sizemotion workspace for the test incident
3. Verify all custom_details are preserved
4. Confirm severity mapping is correct
5. Test deduplication with same dedup_key

Field Mapping

PagerDuty to Sizemotion

All PagerDuty Events API v2 fields are preserved and mapped to Sizemotion:

Severity Mapping

PagerDuty severity values automatically map to Sizemotion severities:

Examples

Python Script

Before (PagerDuty):

import requests

response = requests.post(
    'https://events.pagerduty.com/v2/enqueue',
    headers={'Authorization': 'Token token=abc123...'},
    json={
        'routing_key': 'R0XXXXXXXXXXXXXXXXXXXXXXXXXX',
        'event_action': 'trigger',
        'dedup_key': 'server_cpu_high_001',
        'payload': {
            'summary': 'High CPU on web-01',
            'severity': 'critical',
            'source': 'monitoring.example.com',
            'custom_details': {
                'cpu_percent': '95',
                'duration': '5m'
            }
        }
    }
)

After (Sizemotion):

import requests

response = requests.post(
    'https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5',
    headers={'Authorization': 'Bearer xyz789...'},
    json={
        'routing_key': 'R0XXXXXXXXXXXXXXXXXXXXXXXXXX',
        'event_action': 'trigger',
        'dedup_key': 'server_cpu_high_001',
        'payload': {
            'summary': 'High CPU on web-01',
            'severity': 'critical',
            'source': 'monitoring.example.com',
            'custom_details': {
                'cpu_percent': '95',
                'duration': '5m'
            }
        }
    }
)

cURL

Before (PagerDuty):

curl -X POST https://events.pagerduty.com/v2/enqueue \
  -H "Authorization: Token token=abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "R0XXXXXXXXXXXXXXXXXXXXXXXXXX",
    "event_action": "trigger",
    "dedup_key": "db-connection-timeout",
    "payload": {
      "summary": "Database connection timeout",
      "severity": "critical",
      "source": "prod-app-01",
      "custom_details": {
        "host": "db-prod-01",
        "timeout": "30s",
        "connection_pool": "exhausted"
      }
    }
  }'

After (Sizemotion):

curl -X POST https://sizemotion.com/api/v1/incidents/webhook/pagerduty/5 \
  -H "Authorization: Bearer xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "R0XXXXXXXXXXXXXXXXXXXXXXXXXX",
    "event_action": "trigger",
    "dedup_key": "db-connection-timeout",
    "payload": {
      "summary": "Database connection timeout",
      "severity": "critical",
      "source": "prod-app-01",
      "custom_details": {
        "host": "db-prod-01",
        "timeout": "30s",
        "connection_pool": "exhausted"
      }
    }
  }'

Full Payload Example

All PagerDuty Events API v2 fields supported:

{
  "routing_key": "R0XXXXXXXXXXXXXXXXXXXXXXXXXX",
  "event_action": "trigger",
  "dedup_key": "memory-alert-web-02",
  "payload": {
    "summary": "High memory usage detected on web-02",
    "source": "prometheus.example.com",
    "severity": "error",
    "timestamp": "2026-02-03T10:30:00Z",
    "component": "webserver",
    "group": "production-us-east",
    "class": "memory",
    "custom_details": {
      "host": "web-02.example.com",
      "memory_percent": "87.5",
      "memory_used_gb": "14.2",
      "memory_total_gb": "16",
      "alert_duration": "5m",
      "runbook": "https://wiki.example.com/runbooks/high-memory"
    }
  },
  "images": [
    {
      "src": "https://prometheus.example.com/graph/memory.png",
      "href": "https://prometheus.example.com/alerts/memory-123",
      "alt": "Memory usage graph"
    }
  ],
  "links": [
    {
      "href": "https://wiki.example.com/runbooks/high-memory",
      "text": "High Memory Runbook"
    },
    {
      "href": "https://grafana.example.com/d/memory-dashboard",
      "text": "Memory Dashboard"
    }
  ],
  "client": "Prometheus AlertManager",
  "client_url": "https://prometheus.example.com/alerts"
}

Troubleshooting

Webhook Not Creating Incidents

Check these common issues:

• Authorization Header: Must use "Bearer " prefix (not "Token token=")
• Team ID: Ensure the team ID in the URL is correct
• API Token Permissions: Token must have incidents:create permission
• URL Format: Should be /api/v1/incidents/webhook/pagerduty/{team_id}
• Content-Type: Must be application/json
• Payload Format: Must include payload object with summary field

Duplicate Incidents

Duplicate prevention is automatic using the dedup_key field:

• Same dedup_key creates only one incident
• Different dedup_keys create separate incidents
• If dedup_key is omitted, a new incident is created each time

Severity Not Mapping Correctly

Verify severity format:

• Must be one of: critical, error, warning, info
• Case-sensitive (use lowercase)
• Default is warning (Sev 3) if omitted

Missing Custom Details

If custom_details are incomplete:

• Verify payload.summary field is present (required)
• Check that JSON is properly formatted
• Review the incident metadata - all PagerDuty fields are preserved under metadata.payload
• Custom details support nested objects and arrays

Testing Your Webhook

To validate the integration:

1. Send a test event using cURL (see examples above)
2. Check your Sizemotion workspace for the test incident
3. Verify all custom_details are captured correctly
4. Confirm tags include enrichment (severity_critical, component_webserver, etc.)
5. Test deduplication by sending the same dedup_key twice

Event Actions

Currently supported event actions:

• ✅ trigger - Creates a new incident (fully supported)
• ⏳ acknowledge - Not yet implemented
• ⏳ resolve - Not yet implemented

Getting Help

If issues persist:

• Check Admin Settings → API Tokens for recent activity
• Review webhook logs in your monitoring tool
• See API Documentation for technical details
• Contact your workspace administrator

What's Supported

• ✅ Events API v2 trigger events - fully compatible
• ✅ All event fields (payload, dedup_key, links, images, etc.)
• ✅ Severity mapping (critical/error/warning/info)
• ✅ Idempotency via dedup_key
• ✅ Auto-assignment to on-call responders
• ✅ PagerDuty-compatible response format

Differences from PagerDuty

Small differences to be aware of:

• routing_key: Not used for routing (use team_id in URL instead)
• event_action: Only trigger creates incidents currently
• Integration format: Webhook-based instead of routing key-based
• Response format: Includes additional sizemotion object with incident details

Next Steps

• API Documentation - Technical webhook reference
• Configure On-Call Schedules - Enable auto-assignment
• Incident Management - Learn about incident workflows
• Team Integrations - Connect other tools