WarnFireDocs

Events API

Send your first event

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

Version 1.0 Status Needs verification For Integration operatorsFor Developers apieventsquickstart

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.

Before you begin

You need:

  • a service and integration key connected to a working escalation policy;
  • the curl command-line client or another HTTPS client; and
  • an on-call responder who knows this test creates a real incident and can page them.

Open an incident

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

curl --include --fail-with-body \
  --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. Paging then begins on the channels selected by the service’s captured escalation policy.

Paging cost: This is a real trigger. Push and email are free; selected SMS and voice deliveries consume allowance or prepaid credits for every destination contacted.

The pieces:

  • integration_key — the secret key for one service, created under 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. See how deduplication keys correlate events . 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 --include --fail-with-body \
  --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.

Verify it worked

  1. Confirm the trigger request returns 202 Accepted with an incident identifier and deduplication key.
  2. Open that incident in WarnFire and confirm it belongs to the intended service and contains the summary, source, and severity you sent.
  3. Confirm the service’s on-call responder receives the expected page.
  4. Send the resolve request and confirm that the same incident closes instead of creating another incident.

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.:

FieldWhat it’s for
descriptionThe longer story (up to 8,192 characters).
linksUp to 20 links — the dashboard, the runbook. Give each a text label.
detailsUp to 64 measurements or facts: {"error_rate": 12.7, "region_healthy": false}.
labelsUp to 64 name/value pairs for filtering, like "team": "payments".
tagsSimple keywords, like "customer-impacting".
component, environment, regionWhere in your world this lives: checkout-api, production, us-west-2.
timestampWhen 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 an authorized human acknowledgement does that. See Triggered and paging for the supported acknowledgement paths.

Next steps