CAD Webhook API

{vendor} is the slug we assign you. Your token identifies you on its own, but the path is still enforced — posting a valid token to the wrong vendor's path returns 404, so a misconfiguration surfaces immediately instead of looking like success.

Authorization: Bearer fd_whk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

x-api-key: <token> is also accepted, for vendors whose outbound-webhook screen only offers a custom header field.

If your console has no header field at all — some offer only a name and a URL — put the token in the path instead:

POST /api/webhooks/cad/{vendor}/{token}

Same credential, same storage, no header required.

How you get one

You don't issue it yourself — the department does, from their Firedesk settings, or we do it with them during onboarding. Ask whoever owns the account, or contact us and we'll arrange it.

What you receive is the full URL and the token, with the vendor slug already filled in. It is displayed once and stored as a keyed hash, so it can never be read back — capture it when it's handed over.

It is a bearer credential: anyone holding it can file incidents into that department. Ask for it through whatever channel you would use for a password, not over email or chat.

More than one key can be active at a time, so rotation has no gap in it. A new key is issued and put in place on your side first; the old one keeps working until it is explicitly revoked. There is no window where deliveries fail, and no need to coordinate a cutover to the second.

This is stricter than most APIs, deliberately. A naive 2026-08-03T14:22:05 from a Central-time ECC is indistinguishable from UTC, and guessing wrong files a dispatch six hours off on a record a department may later be audited against — with nothing about it looking wrong afterward. A rejection you can see and fix is better than a silent error you can't.

{
  "schema_version": "1.0",
  "event": "incident.updated",        // incident.created | incident.updated | incident.closed
  "sent_at": "2026-08-03T14:22:05-05:00",

  "incident": {
    "external_id": "F23112801308",    // REQUIRED - your stable id for this call
    "cad_number": "SCC-2026-88213",   // the ECC's own incident number, if different
    "status": "active",               // active | closed | cancelled
    "dispatched_at": "2026-08-03T14:21:58-05:00",   // REQUIRED
    "closed_at": null,

    "type": { "code": "MVC", "subcode": "INJ", "label": "Motor Vehicle Crash" },
    "priority": "1",
    "agency": "ST CLAIR ECC",
    "narrative": "Two vehicles, one entrapment",

    "location": {
      "street": "426 S MAIN ST",
      "unit": "APT 3B",
      "place_name": "Lincoln Elementary",
      "city": "O'Fallon",
      "state": "IL",
      "postal_code": "62269",
      "cross_streets": ["N MAIN ST", "W 1ST ST"],
      "latitude": 38.5921,
      "longitude": -89.9112
    },

    "units": [
      { "id": "E1", "name": "Engine 1", "status": "onScene",
        "status_at": "2026-08-03T14:29:11-05:00", "agency": "OFD" }
    ],

    "responders": [
      { "id": "dev-77", "name": "A. Smith", "response": "Responding",
        "at": "2026-08-03T14:22:30-05:00" }
    ],

    "comments": [
      { "id": "c-9931", "body": "Caller reports smoke",
        "at": "2026-08-03T14:23:40-05:00", "author": "DISP12" }
    ]
  }
}

Only two fields are required for the whole payload: incident.external_id and incident.dispatched_at. Everything else — including the units, responders and comments arrays — can be omitted, sent empty, or sent null.

In the tables below, a yes in the Req column means required within the object it belongs to, not that the object itself has to be sent. So a unit entry must carry an id and a status— but you never have to send a unit at all.

Envelope

incident

incident.location

All optional — but send coordinates if you have nothing else. When city / state / postal code are missing and coordinates are present, Firedesk reverse-geocodes the rest.

incident.units — apparatus

A rig with a CAD status. Not people.

The array is optional — omit it, or send it empty or null, if you have no unit data. The columns below describe one entry, once you do send one.

Send your own status vocabulary. dispatched, enroute, onScene, whatever your CAD uses. Each department maps those to run-report timestamps themselves; do not translate them for us. Send one entry per transition — a unit that went dispatched → enroute → onScene should produce all three, and re-sending them is harmless.

incident.responders — people

A person who declared a response, not a rig. The array is optional — omit it entirely if your system is apparatus-only. The columns below describe one entry.

incident.comments

The array is optional. The columns below describe one entry.

Send the full comment list on every delivery; we de-duplicate on id. A stable id matters: without one we would have to compare comment text, which silently collapses two identical lines a dispatcher legitimately typed twice.

Separate endpoint, on purpose. A GPS stream runs orders of magnitude more often than a dispatch update, and putting it on the incident endpoint would mean re-sending a whole incident envelope several times a minute per call.

{
  "positions": [
    {
      "responder_id": "dev-77",
      "latitude": 38.5921,
      "longitude": -89.9112,
      "at": "2026-08-03T14:25:00-05:00",
      "accuracy_m": 12,
      "name": "A. Smith",
      "response": "Responding",
      "incident_external_id": "F23112801308"
    }
  ]
}

Up to 500 per request. responder_id, latitude, longitude and at are required; the rest are optional. Send incident_external_id when you know it — Firedesk geofences arrivals against the incident scene and each station, and that arrival becomes the responder's on-scene time.

A 422 looks like:

{
  "message": "Payload does not match the FireDesk CAD schema",
  "errors": {
    "incident.dispatched_at": [
      "The incident.dispatched_at field must carry an explicit UTC offset (e.g. 2026-08-03T14:22:05-05:00, or ...Z)."
    ]
  }
}

Every POST — accepted or rejected — is recorded with the body exactly as you sent it, so "we sent it and you didn't get it" can be settled without asking you for replays. Records are kept 7 days.

Example

curl -X POST https://api.firedesk.io/api/webhooks/cad/{vendor} \
  -H "Authorization: Bearer fd_whk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "1.0",
    "event": "incident.created",
    "sent_at": "2026-08-03T14:22:05-05:00",
    "incident": {
      "external_id": "F23112801308",
      "status": "active",
      "dispatched_at": "2026-08-03T14:21:58-05:00",
      "type": { "code": "MVC" },
      "location": {
        "street": "426 S MAIN ST",
        "city": "Lebanon",
        "state": "IL",
        "postal_code": "62269",
        "latitude": 38.5921,
        "longitude": -89.9112
      },
      "units": [
        { "id": "E1", "status": "dispatched", "status_at": "2026-08-03T14:22:00-05:00" }
      ]
    }
  }'

• Send an update whenever anything changes — a unit status, a comment, closure. Ingestion is idempotent, so re-sending an unchanged payload is a no-op.
• Order is not assumed. We compare sent_at and discard a delivery older than the last one processed.
• Never rejected for an unmapped code. Unknown unit ids and type codes create the incident anyway and surface in the UI for the department to map. Only a malformed payload is rejected.
• No retry endpoint. If we return non-2xx, retry with backoff; the body is stored either way.

A vendor whose schema can't be changed gets a transformer — a small translation layer on our side that converts your body into this contract before validation. You keep sending exactly what you already send.

To build one we need a sample payload for each event you emit — a dispatch, a unit status change, and a close — plus whatever documentation you have for the fields. Real captured bodies are more useful than a spec, since they show the edge cases a spec usually omits.

Field names don't have to match and structure doesn't have to match. The two things we can't derive are a stable identifier for each call and an unambiguous dispatch time — if your payload carries those, the rest is a mapping exercise.