Events API

Send your first event

Open an incident with one request, then close it with another.

An event is a short message telling WarnFire something happened: “a problem started”, “it’s still going”, or “it’s fixed.” WarnFire turns those messages into incidents and pages people.

Open an incident

Send a POST request to https://api.warnfire.com/v1/events with a JSON body:

curl --request POST 'https://api.warnfire.com/v1/events' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "YOUR-INTEGRATION-KEY",
    "event_action": "trigger",
    "dedup_key": "checkout-api/high-error-rate",
    "payload": {
      "summary": "Checkout error rate above 10%",
      "source": "prometheus",
      "severity": "critical"
    }
  }'

WarnFire answers 202 Accepted with the incident’s ID — and the on-call responder’s phone is already buzzing.

The pieces:

integration_key — the secret key for one service, created under Configuration → Services. It both proves who you are and tells WarnFire which service the problem belongs to.
event_action: "trigger" — “a problem started.”
dedup_key — your name for this specific problem (more below). If you leave it out, WarnFire generates one and returns it.
payload — the human-facing part. Three fields are required:
- summary — one plain sentence a half-asleep responder will read first.
- source — where this came from (a hostname, a monitor name).
- severity — critical, error, warning, or info.

Close it when it’s fixed

curl --request POST 'https://api.warnfire.com/v1/events' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "YOUR-INTEGRATION-KEY",
    "event_action": "resolve",
    "dedup_key": "checkout-api/high-error-rate"
  }'

Same dedup_key, action resolve — the incident closes, and the timeline records how long it lasted.

Make incidents genuinely useful

Everything else in payload is optional, but the more you send, the less a responder has to go digging at 3 a.m.:

Field	What it’s for
`description`	The longer story (up to 8,192 characters).
`links`	Up to 20 links — the dashboard, the runbook. Give each a `text` label.
`details`	Up to 64 measurements or facts: `{"error_rate": 12.7, "region_healthy": false}`.
`labels`	Up to 64 name/value pairs for filtering, like `"team": "payments"`.
`tags`	Simple keywords, like `"customer-impacting"`.
`component`, `environment`, `region`	Where in your world this lives: `checkout-api`, `production`, `us-west-2`.
`timestamp`	When the problem was observed (RFC 3339 format). WarnFire separately records when it received the event.

A note on `acknowledge`

There’s a third action, acknowledge, which your monitoring system can send. It’s written into the incident’s history — but it does not stop the paging. Only a real person acknowledging (in the app, console, or Slack) does that. See The life of an incident for why.

What next