PagerDuty Integration

Use this guide to create PagerDuty incidents automatically when PayloadRelay receives a webhook payload.

Purpose

This workflow helps you:

• Create a PagerDuty service integration.
• Register PagerDuty as a relay target using the integration (routing) key.
• Attach the target to an endpoint output.
• Validate incident creation with a test delivery.

Prerequisites and permissions

• PagerDuty account with permission to create services or integrations.
• Access to Relay targets and Endpoints in PayloadRelay.

Payload format

PayloadRelay sends a PagerDuty Events API v2 trigger event:

{
  "routing_key": "<your-integration-key>",
  "event_action": "trigger",
  "dedup_key": "<endpoint-id>:<delivery-uuid>",
  "payload": {
    "summary": "<first 1024 chars of stringified payload or endpoint name>",
    "source": "PayloadRelay",
    "severity": "error",
    "custom_details": { ...original payload... }
  }
}

The dedup_key is stable per delivery (including retries), so PagerDuty will deduplicate multiple retries for the same event into a single incident.

Severity

The default severity is error. You can change this in the relay target settings to one of info, warning, error, or critical.

Step-by-step workflow

1. Create a PagerDuty service integration

1. In PagerDuty, navigate to Services → your service (or create a new one).
2. Select the Integrations tab and click Add an integration.
3. Choose Events API v2 as the integration type.
4. Click Add. PagerDuty generates an Integration Key (a 32-character hex string).
5. Copy the integration key.

2. Add a PagerDuty relay target

1. Open Relay targets in PayloadRelay.
2. Select Add target.
3. Choose PagerDuty as the type.
4. Paste your Integration Key into the field.
   • The key must be exactly 32 hexadecimal characters.
   • The key is stored encrypted and is never shown again after saving.
5. Optionally add a name and description, then save.

No email confirmation is required — the target is ready immediately.

3. Attach the target to an endpoint

1. Open the endpoint create/edit page.
2. In Target destinations, select your PagerDuty target.
3. Save the endpoint.

4. Validate delivery

1. On the Relay targets page, find your PagerDuty target and click Test.
2. PayloadRelay sends a trigger event immediately followed by a resolve event (using the same dedup_key) so the test does not leave an open incident.
3. Confirm you see a briefly-open-then-resolved incident in PagerDuty.

Security

• The integration key is stored securely and is not shown again after saving.
• To rotate the key, edit the target and enter the new key.

Retry behavior

Failed deliveries are retried up to 5 times with exponential back-off. PagerDuty is highly available; transient failures are rare but handled automatically.

Troubleshooting