Events API

Deduplication and safe retries

Two small fields guarantee one problem means one incident — no matter how flaky the network.

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 delivery attempt. Sent a request but never got an answer because the network dropped? Send it again with the same client_event_id — WarnFire recognizes the repeat, changes nothing, and returns the original answer. This is what makes retrying always safe.

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, an updated description) becomes a numbered update on the incident — visible in the console and in the app’s Updates tab. Responders see the situation evolving in one place, with nobody paged twice.

Cheat sheet