Documentation
Contact Support

Alert Deduplication

Alert deduplication helps you avoid duplicate alerts by automatically grouping related signals together within a configurable time window. Instead of creating separate alerts for the same problem occurring multiple times, FireHydrant groups them into a single alert and increments an alert count.

Overview

When your monitoring systems send multiple alerts about the same issue to FireHydrant, deduplication ensures you're not overwhelmed with redundant notifications. FireHydrant uses an idempotency key to identify and group related alerts — any signals with the same idempotency key within the deduplication window are treated as duplicates of the original alert.

For example, if your CPU monitoring tool sends "CPU usage is high" every minute for 30 minutes, you'll receive one alert with a count of 30, rather than 30 separate alerts.

How it works

Setting the idempotency key

Each signal (event) you send to FireHydrant must include an idempotency_key in the event payload. This key uniquely identifies the alert condition and is the basis for deduplication:

{
  "summary": "CPU usage too high",
  "idempotency_key": "cpu-monitor-prod-server-1",
  "status": "OPEN"
}

The idempotency key should be:

  • Unique per alert condition — different problems should have different keys
  • Consistent across occurrences — the same condition should always use the same key
  • Max 255 characters

Configuring the deduplication window

When you create a signal rule, you configure how long alerts should be deduplicated based on their idempotency key. The deduplication window is a time period starting from when the first alert is created.

Available deduplication durations:

  • 5 minutes
  • 15 minutes
  • 30 minutes
  • 1 hour
  • 2 hours
  • 3 hours
  • 6 hours
  • 12 hours
  • 24 hours (default)

What happens during the window

While the deduplication window is open:

  1. Any new signal with the same idempotency key is recognized as a duplicate
  2. Instead of creating a new alert, the duplicate is grouped with the original alert
  3. The alert's occurrence count increments, and its timestamp updates to reflect the latest duplicate
  4. Responders receive only one alert and notification for the entire group

After the window expires

Once the deduplication window expires:

  • New signals with the same idempotency key will create a new alert instead of being grouped with the old one
  • This is useful for recurring problems — each occurrence gets its own alert after the window closes
  • The system runs a background check every 5 minutes to identify expired deduplication windows

Setting up deduplication for a rule

  1. Navigate to your team's Signals settings
  2. Click Create Rule or edit an existing rule
  3. In the rule details panel, find the "Idempotency Key Deduplication" section
  4. Select your desired deduplication duration from the dropdown (defaults to 24 hours)
  5. Save the rule

The deduplication setting applies to all signals matching that rule. You can adjust it at any time by editing the rule.

Best practices

Choose an appropriate window:

  • Short windows (5–30 minutes) — use for transient issues you expect to resolve quickly, or for high-volume monitoring where you want frequent alerts about ongoing problems
  • Long windows (6–24 hours) — use for problems that may take time to diagnose and fix, or to reduce alert fatigue for known recurring issues

Design your idempotency key carefully:

  • Include enough context to be unique (e.g., service-name-error-type-instance) but not so much that transient variations create false duplicates
  • Avoid timestamps or random values in the key — these will prevent deduplication
  • Test your key design with a few signals to ensure related alerts group correctly

Monitor your alert counts:

  • A single alert with a high occurrence count may indicate either a real ongoing issue or a misconfigured idempotency key
  • If you're seeing many single-occurrence alerts for what should be the same problem, check that your monitoring system is sending the same idempotency key consistently

Related

  • [doc:events-data-model] — Details on the idempotency key field and other event properties
  • [doc:signals-configuring-event-sources] — How to configure where your signals come from
  • [doc:signals-alert-rules] — Creating and managing signal rules

Updated 4 days ago