Deduplication and retries
Group recurring alerts by service or key, and distinguish new alerts from retried HTTP requests.
Two different problems
Deduplication groups recurring monitoring reports into one open incident. Each grouped report adds an alert to the timeline.
Idempotency recognises a retry of the exact same request. It replays the original response without adding another incident or timeline entry.
No key: group by service
With service deduplication enabled, a trigger without deduplication_key matches the latest triggered or acknowledged incident for that service inside the configured window. The title does not have to match. An unkeyed request can also join an eligible incident that was originally created with a key.
For example, with a 120-second window:
| Time since creation | Incoming title | Outcome |
|---|---|---|
| 0 seconds | Database unavailable | Create an incident |
| 10 seconds | Connection timeout | Add an alert to that incident |
| 50 seconds | Replication lag | Add an alert to that incident |
| 121 seconds | Connection timeout | Create another incident |
The window is measured from incident creation, not from the most recent alert. Repeats do not extend it.
With a key: match service and key
Add an explicit key when one service has independent checks:
--form-string "deduplication_key=production-db-connectivity"A trigger with this key matches only an open incident for the same service with the same key inside the window. A different key creates a separate incident. Changing the title while keeping the same key does not force a new incident.
Choose a stable key such as a check name or monitored resource identifier. Do not generate a new random key for every polling cycle if you want those cycles grouped.
Service settings still apply
When deduplication is disabled, triggers create new incidents even if an explicit key is supplied. A resolved incident is not a deduplication candidate. The newest matching open incident is used when several are eligible.
Grouping preserves the existing title, description, severity, and acknowledged state. It records that another API alert was received; it does not overwrite the incident with the latest request fields.
Retry an exact request safely
Add a unique identifier for a single monitoring event:
--header "Idempotency-Key: monitoring-event-20261031-0001"Reuse it only when retrying that same event with the same fields. A distinct later event needs a distinct idempotency key.
- The API retains the stored response for 24 hours.
- An identical retry returns the original response and HTTP status, including
201if that was the original result. - Reusing the key with different fields returns
409. - Idempotency is scoped to the API credential, so changing credentials does not preserve that retry identity.
- After expiry, the request is processed again; normal deduplication then determines whether to group it.
Use idempotency when a timeout leaves you unsure whether the server processed the request. Use deduplication for continuing reports of the same service problem.