Route Flowtriq DDoS alerts to PagerDuty
with severity escalation

Back to Blog

The Problem with Flat-Priority Alerting

DDoS detection without severity-aware alerting creates two failure modes. If every event triggers a high-priority page, the on-call engineer experiences alert fatigue and starts ignoring notifications. If nothing triggers a page, critical attacks go unnoticed until customers report downtime. The solution is mapping Flowtriq's four severity levels to PagerDuty's urgency and escalation system so each event type gets the response it deserves.

This guide covers the complete integration: creating PagerDuty services, generating integration keys, configuring severity mapping in Flowtriq, setting up deduplication to prevent alert storms, building escalation policies, and using PagerDuty's acknowledgment workflow to coordinate response.

Architecture Overview

Flowtriq sends events to PagerDuty using the Events API v2. Each event includes a severity level, a deduplication key, and structured metadata about the attack. PagerDuty uses this information to create, update, or resolve incidents according to your escalation policy.

The recommended architecture uses two PagerDuty services:

• Flowtriq DDoS Monitoring: Receives info and warning events. Configured with a low-urgency notification rule (push notification only, no phone calls).
• Flowtriq DDoS Critical: Receives high and critical events. Configured with a high-urgency notification rule and multi-level escalation.

This separation ensures that routine traffic anomalies never page anyone, while genuine attacks trigger immediate response.

Step 1: Create PagerDuty Services

Log in to PagerDuty and navigate to Services > Service Directory > New Service.

Monitoring Service

Create the first service with these settings:

• Name: Flowtriq DDoS Monitoring
• Integration: Events API v2
• Urgency: Low (use "dynamic" if you want PagerDuty to infer urgency from the event payload)
• Escalation Policy: A single-level policy that notifies via push notification only

After creating the service, PagerDuty displays an Integration Key (also called a Routing Key). Copy this value.

Critical Service

Create the second service:

• Name: Flowtriq DDoS Critical
• Integration: Events API v2
• Urgency: High
• Escalation Policy: Multi-level (we will configure this in Step 4)

Copy the Integration Key for this service as well.

Step 2: Configure Flowtriq Alert Channels

In the Flowtriq dashboard, navigate to Settings > Alert Channels > Add Channel and select PagerDuty. Create two channels, one for each PagerDuty service.

Monitoring Channel

{
  "channel": "pagerduty",
  "name": "PagerDuty - Monitoring",
  "integration_key": "your-monitoring-integration-key",
  "severity_filter": ["info", "warning"],
  "dedup_key_template": "flowtriq-{{node_id}}-{{attack_id}}",
  "auto_resolve": true
}

Critical Channel

{
  "channel": "pagerduty",
  "name": "PagerDuty - Critical",
  "integration_key": "your-critical-integration-key",
  "severity_filter": ["high", "critical"],
  "dedup_key_template": "flowtriq-{{node_id}}-{{attack_id}}",
  "auto_resolve": true
}

Step 3: Severity Mapping

Flowtriq maps its internal severity levels to PagerDuty's Events API v2 severity field as follows:

Flowtriq Severity    PagerDuty Severity    Typical PD Urgency
-----------------------------------------------------------------
info                 info                  Low (suppressed)
warning              warning               Low
high                 error                 High
critical             critical              High (immediate page)

PagerDuty's Events API v2 accepts four severity values: info, warning, error, and critical. Flowtriq sends the appropriate value automatically based on the attack classification.

If you prefer to override the default mapping, you can specify a custom mapping in the channel configuration:

{
  "channel": "pagerduty",
  "name": "PagerDuty - Custom Mapping",
  "integration_key": "your-key",
  "severity_filter": ["warning", "high", "critical"],
  "severity_mapping": {
    "warning": "info",
    "high": "warning",
    "critical": "error"
  },
  "dedup_key_template": "flowtriq-{{node_id}}-{{attack_id}}"
}

This custom mapping downgrades all severity levels by one tier, which can be useful if your Flowtriq detection thresholds are set aggressively and you want to reduce PagerDuty noise without adjusting the detection policies themselves.

Step 4: Build Escalation Policies

In PagerDuty, navigate to Escalation Policies > New Escalation Policy and create a policy for your critical service. A battle-tested DDoS escalation policy typically has three levels:

1. Level 1 (immediate): The primary on-call network engineer. Notified by phone call and SMS. If unacknowledged within 5 minutes, escalate.
2. Level 2 (5 minutes): The secondary on-call engineer and the NOC team lead. Notified by phone call. If unacknowledged within 10 minutes, escalate.
3. Level 3 (15 minutes): The Director of Infrastructure and the incident commander on-call schedule. Notified by phone call, SMS, and email to the engineering-alerts distribution list.

Assign this escalation policy to the "Flowtriq DDoS Critical" service you created in Step 1.

For the monitoring service, a single-level escalation policy with push notifications is sufficient. These events should be reviewed during business hours, not in the middle of the night.

Deduplication and Alert Grouping

The dedup_key_template field is critical for preventing alert storms during large attacks. Flowtriq generates a deduplication key using the node ID and attack ID, which means:

• Multiple updates about the same attack on the same node are grouped into a single PagerDuty incident
• If an attack escalates in severity (e.g., from warning to critical), the existing incident is updated rather than creating a new one
• When the attack ends, Flowtriq sends a resolve event with the same dedup key, automatically closing the incident

Here is an example of the Events API v2 payload that Flowtriq sends to PagerDuty:

{
  "routing_key": "your-integration-key",
  "event_action": "trigger",
  "dedup_key": "flowtriq-edge-gw-01-atk-789012",
  "payload": {
    "summary": "DDoS: SYN Flood on 203.0.113.45 (847,320 pps / 412 Mbps)",
    "source": "edge-gw-01",
    "severity": "critical",
    "component": "203.0.113.45",
    "group": "edge-routers",
    "class": "DDoS Attack",
    "custom_details": {
      "attack_vector": "SYN Flood",
      "target_ip": "203.0.113.45",
      "packets_per_second": 847320,
      "bits_per_second": 412000000,
      "baseline_deviation": "12.4x",
      "node_id": "edge-gw-01",
      "attack_id": "atk-789012",
      "dashboard_url": "https://flowtriq.com/incidents/atk-789012"
    }
  },
  "links": [
    {
      "href": "https://flowtriq.com/incidents/atk-789012",
      "text": "View in Flowtriq Dashboard"
    }
  ]
}

The custom_details object appears in PagerDuty's incident detail view, giving the responder all the context needed to begin triage without leaving PagerDuty.

Acknowledging and Resolving from PagerDuty

When an on-call engineer acknowledges a Flowtriq incident in PagerDuty, the acknowledgment status is visible in the Flowtriq dashboard as well. This two-way visibility ensures the broader team knows someone is actively investigating the attack.

When Flowtriq detects that an attack has ended, it sends an event_action: "resolve" payload to PagerDuty with the matching dedup key. The incident is closed automatically. If the attack resumes within the PagerDuty service's auto-resolve window, a new incident is created.

You can also resolve incidents manually from PagerDuty if needed. Manual resolution does not affect Flowtriq's detection. The agent continues monitoring regardless of the PagerDuty incident status.

Advanced: Dynamic Urgency with Event Intelligence

If you have PagerDuty's Event Intelligence add-on, you can configure the critical service to use dynamic urgency. This allows PagerDuty to infer urgency from the event severity field, so a single service can handle both high-urgency (critical) and low-urgency (high) events:

• critical: Triggers high-urgency notification (phone call + SMS)
• error: Triggers high-urgency notification (phone call)
• warning: Triggers low-urgency notification (push only)
• info: Suppressed (visible in the incident list but no notification)

With dynamic urgency, you can simplify to a single PagerDuty service and a single Flowtriq alert channel instead of two of each.

Testing the Integration

Click the Test button next to each PagerDuty channel in the Flowtriq dashboard. This sends a test event to PagerDuty that creates a real incident. Verify that:

• The incident appears on the correct PagerDuty service
• The escalation policy triggers the expected notification
• The custom details include all Flowtriq metadata
• The incident link points to a valid Flowtriq dashboard URL

Acknowledge and resolve the test incident in PagerDuty to confirm the full lifecycle works.

PagerDuty integration is available on all Flowtriq plans at $9.99/node/month. Configure as many alert channels as you need with independent severity filters and escalation paths. Start your free trial to connect Flowtriq to your PagerDuty account today.

Back to Blog

Related Articles