Events API

Deduplication and safe retries

Use correlation and idempotency fields to keep repeated alerts and network retries from creating unintended incidents.

Monitoring systems repeat themselves. Networks hiccup and requests get retried. Without protection, one bad night could page your responder nine times for one problem. Two fields prevent that, and they solve two different problems — the most common mistake is mixing them up.

dedup_key — “which problem is this?”

The dedup_key is your name for a problem, like checkout-api/high-error-rate. The rule is simple:

While an incident with that key is open, more triggers with the same key join it instead of opening a new one.

• Your monitor fires every minute during an outage? One incident, with updates — not sixty incidents.
• The resolve event uses the same key, which is how WarnFire knows which incident to close.
• After an incident resolves, the key is free again — the next trigger with it opens a fresh incident.

Choose keys that mean “this problem at this place”: a good pattern is component/what-is-wrong. Don’t include timestamps or random values, or every event becomes its “own problem” and dedup can’t help you.

client_event_id — “is this the same message again?”

The client_event_id identifies one logical event request across delivery attempts. Sent a request but never got an answer because the network dropped? Retry the same request with the same client_event_id. When the action, dedup key, and canonical payload are unchanged, WarnFire recognizes the repeat, makes no second change, and returns the original answer.

Use something unique per delivery: a UUID, or your tool’s own message ID.

The safety catch

A client_event_id is bound to exactly the request it first arrived with. If the same ID comes back meaning something different — say, an ID first used for a trigger later arrives on a resolve — WarnFire refuses it with a 409 error rather than guess.

That strictness is protection: a mixed-up or malicious replay can never quietly close an incident that should still be paging.

Updates, not duplicates

While an incident is open, a trigger with the same dedup_key but new content (a changed measurement or updated description) becomes a numbered update on the incident — visible in the console and in the app’s Updates tab. The update does not start a second escalation merely because it arrived. The existing policy can still continue through later configured steps or channels.

Cheat sheet

Apply these fields to the trigger example and resolve example , then use the OpenAPI document for the complete request schema.