PagerDuty Integration

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

Purpose#

Use this guide to:

• Create a PagerDuty service integration.
• Save the integration key as a relay target.
• Attach the target to an endpoint destination.
• Create a test incident with a test delivery.

Before you start#

• A PagerDuty account with permission to create a service or an integration.
• 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": "<info|warning|error|critical>",
    "custom_details": { ...original payload... }
  }
}

The dedup_key is stable for each delivery, with the retries. PagerDuty thus puts more than one retry of the same event into one incident.

If the inbound payload is not a JSON object, PayloadRelay puts it in an object before it sends the payload to PagerDuty. This applies to plain text, XML text, an array, and a scalar JSON value:

{
  "payload": "<original payload>",
  "payloadText": "<stringified payload>"
}

Severity#

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

Procedure#

1. Create a PagerDuty service integration#

1. In PagerDuty, open Services and select your service, or create a service.
2. Select the Integrations tab, then select Add an integration.
3. Select Events API v2 as the integration type.
4. Select Add. PagerDuty makes an Integration Key, which is a 32-character hexadecimal string.
5. Copy the integration key.

2. Add a PagerDuty relay target#

1. Open Relay targets in PayloadRelay.
2. Select Add target.
3. Select PagerDuty as the type.
4. Paste the Integration Key into the field.
   • The key must have exactly 32 hexadecimal characters.
   • PayloadRelay stores the key encrypted, and it does not show the key after you save.
5. Select the PagerDuty severity for the incidents that this target creates.
6. If a name and a description are necessary, add them. Then save.

The target needs no email confirmation. It is available immediately.

You can create more than one PagerDuty relay target, for example, one target for each PagerDuty service or integration key. Give each target a clear name, and you can then select the correct service in the endpoint destinations.

3. Attach the target to an endpoint#

1. Open the endpoint create page or the endpoint edit page.
2. In Outputs, select the PagerDuty target.
3. Save the endpoint.

4. Test delivery#

1. On the Relay targets page, find the PagerDuty target and select Send test.
2. PayloadRelay sends a trigger event, then a resolve event with the same dedup_key. The test leaves no open incident.
3. Make sure that PagerDuty shows an incident that opened for a short time and then resolved.

Security#

• PayloadRelay stores the integration key in a safe location, and it does not show the key after you save.
• To change the key, edit the target and enter the new key.

Retry behavior#

A failed delivery uses the standard automatic retry schedule of PayloadRelay, in the limit of the plan. PayloadRelay retries a temporary PagerDuty error automatically.

Troubleshooting#