PagerDuty

Datafly Signal triggers PagerDuty incidents from Signal events using the Events API v2. Useful for waking the on-call engineer when delivery error rates spike, payments fail at the threshold, or a business-critical event needs an immediate human response.

Prerequisites

• A PagerDuty account with at least one service.
• Permission to add integrations to that service.
• A clear sense of which events should page on-call — PagerDuty is for “wake someone up” alerts, not general notifications. For general notifications use Microsoft Teams instead.

Get your credentials

Step 1: Pick or create a PagerDuty service

1. In PagerDuty, go to Services > Service Directory.
2. Click New Service if you do not already have one for Signal alerts.
3. Set the name (e.g. Signal Delivery Alerts), an escalation policy, and an incident urgency policy.
4. Click Create.

Step 2: Add an Events API v2 integration

1. On the service page, open the Integrations tab.
2. Click Add an integration.
3. Search for and select Events API V2.
4. Click Add Integration.

Step 3: Copy the routing key

PagerDuty now shows the Integration Key (also called the Routing Key) — a 32-character hex string.

5. Copy the key.

Configure in Signal

Configuration fields

Management UI setup

1. Go to Integrations > Add Integration > PagerDuty.
2. Paste the routing_key.
3. Select the General preset.
4. Leave consent categories at the default (essential) — PagerDuty traffic is operational alerting.
5. Click Save.

Management API setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "pagerduty",
    "name": "PagerDuty - Signal Delivery Alerts",
    "enabled": true,
    "config": {
      "routing_key": "0123456789abcdef0123456789abcdef",
      "severity_default": "error"
    },
    "consent_categories": ["essential"]
  }'

API endpoint

POST https://events.pagerduty.com/v2/enqueue
Content-Type: application/json

The routing key is sent in the JSON body, not in a header. Signal handles this automatically — the customer never embeds the key in mappings.

Event mapping

General preset

Every event renders into the Events API v2 payload shape. Default mappings are:

Example: Error Occurred

Datafly.js call (or server-side Datafly.track()):

datafly.track("Error Occurred", {
  message: "Stripe webhook handler timed out after 30s",
  error_class: "stripe.webhook.timeout",
  order_id: "ORD-001",
  attempt: 3
});

PagerDuty payload sent by Signal:

{
  "routing_key": "0123456789abcdef0123456789abcdef",
  "event_action": "trigger",
  "dedup_key": "stripe.webhook.timeout",
  "payload": {
    "summary": "Stripe webhook handler timed out after 30s",
    "severity": "error",
    "source": "datafly-signal",
    "custom_details": {
      "message": "Stripe webhook handler timed out after 30s",
      "error_class": "stripe.webhook.timeout",
      "order_id": "ORD-001",
      "attempt": 3
    }
  }
}

PagerDuty creates a new incident on the first event with a given dedup_key and folds subsequent matching events into that incident until it is resolved.

Recommended use patterns

• Delivery error thresholds. Configure a pipeline filter so events fire only when a vendor’s error rate crosses a threshold. Avoid raw error pass-through, which will drown the on-call rotation.
• Business-rule incidents. Trigger for high-value events (e.g. an order above £10,000 fails) so the right team intervenes before the customer churns.
• Payment processor outages. Wire Payment Failed with dedup_key set to the processor name to surface a single incident per outage window.

Identity

Signal sends no identity data to PagerDuty. The Events API v2 payload contains only the event headline, severity, source, dedup key, and the explicitly mapped property values inside custom_details. IP address, user agent, and cookie identifiers are stripped before delivery.

PagerDuty is for on-call signalling, not analytics. If you map sensitive customer fields into custom_details they will appear in incident timelines — review what you forward.

Consent

The default consent category is essential. PagerDuty traffic is treated as operational alerting and fires regardless of the end-user’s marketing-consent state. This matches how most legal teams classify on-call paging.

If your governance policy requires this integration to honour marketing or analytics consent, change the consent category in the Management UI — but be aware that withdrawing consent will then silence incidents about events triggered by that user.

Verify it’s working

Step 1: Fire a test event

datafly.track("Error Occurred", {
  message: "Test incident from Datafly Signal",
  error_class: "signal.test"
});

Step 2: Check PagerDuty

Within a few seconds, a new incident titled Test incident from Datafly Signal should appear on the service.

Step 3: Inspect the Signal event debugger

In the Signal Management UI, open the integration’s Recent Events tab. You should see the event with a 202 response (PagerDuty’s success code) and the full Events API v2 payload.

Step 4: Resolve the test incident

Resolve the test incident manually in PagerDuty so it does not leave on-call noise behind.

Troubleshooting

See also

• PagerDuty Events API v2 reference
• PagerDuty deduplication guide
• Microsoft Teams integration — for general-purpose channel notifications instead of paging