What is a Monitorable Incident?

A monitorable incident is Hyperion's record that ADT is handling an alarm at a monitorable. It is not a Hyperion event. You create events. Incidents are opened when ADT starts working an alarm, or when you create one for a monitorable.

A monitorable can have only one active incident at a time. If ADT works several alarms at the monitorable while the incident is active, the operator actions for all of them attach to that one incident. The incident stays open until ADT resolves it.

If a new alarm arrives while the incident is RESOLVED, the incident goes back to OPEN and resolvedAt is cleared. You receive a monitorable-incident:update webhook. Once the incident is CLOSED, a new alarm opens a new incident.

You receive a Hyperion incident id and action types such as DIALED_PRIMARY_CONTACT.

Creating an event is something you send to Hyperion. A monitorable incident action is an operator action ADT already took (manually or automatically) that Hyperion sends to you.

Monitorable incident actions

Actions are the operator steps on that incident. Each action is one operator action an ADT agent or the application took, so you can see how the incident is being handled: they dialed the primary contact, they notified police, they closed it.

The first action opens the incident. Later actions attach to the same incident. A close action (AGENT_CLOSED_INCIDENT or ELECTRONIC_CANCEL) resolves the incident. Actions can still attach after the incident is resolved.

Late operator actions for an alarm whose incident is already CLOSED still attach to that incident. Its status stays CLOSED.

Incident status

Every incident has a status:

Status	Meaning
OPEN	ADT is handling the alarm
RESOLVED	ADT finished handling the alarm. resolvedAt holds when that happened
CLOSED	The incident is permanently closed. closedAt holds when that happened

resolvedAt, closedAt, and reason are left out of the response until they are set.

Closing after inactivity

Hyperion closes an incident on its own after 30 minutes with no activity. Activity is a new event you add to the incident or a new operator action from ADT. Each one restarts the 30 minutes.

An incident closed this way has closedAt set and no reason, whether it was OPEN or RESOLVED. You receive a monitorable-incident:update webhook.

In sandbox, you can simulate these operator actions. See Sandbox incident flows.

How to receive incident updates

Subscribe to webhooks. That is how you learn about incidents in real time.

• Webhooks concept — activity types and payload shape
• Receive Notifications guide — how to create and subscribe

Subscribe to:

• monitorable-incident:create when the incident is opened
• monitorable-incident:action:create when another operator action arrives
• monitorable-incident:update when the incident status changes, such as when it is resolved, reopened, or closed

Sample webhook payloads

Webhook data for incidents and actions is identifier-only. Use GET /v1/monitorables/:monitorableId/incidents/:incidentId (and the actions list) to load status, timestamps, and action type.

Incident created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "entityId": "550e8400-e29b-41d4-a716-446655440002",
  "entityType": "MONITORABLE_INCIDENT",
  "activityType": "monitorable-incident:create",
  "scope": "monitorable-incident:read",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "partnerId": "550e8400-e29b-41d4-a716-446655440001",
    "monitorableId": "550e8400-e29b-41d4-a716-446655440003",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Incident updated

{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "entityId": "550e8400-e29b-41d4-a716-446655440002",
  "entityType": "MONITORABLE_INCIDENT",
  "activityType": "monitorable-incident:update",
  "scope": "monitorable-incident:read",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "partnerId": "550e8400-e29b-41d4-a716-446655440001",
    "monitorableId": "550e8400-e29b-41d4-a716-446655440003",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:45:00Z"
  },
  "createdAt": "2024-01-15T10:45:01Z"
}

Incident action created

{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "partnerId": "550e8400-e29b-41d4-a716-446655440001",
  "entityId": "550e8400-e29b-41d4-a716-446655440002",
  "entityType": "MONITORABLE_INCIDENT",
  "activityType": "monitorable-incident:action:create",
  "scope": "monitorable-incident:read",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440005",
    "partnerId": "550e8400-e29b-41d4-a716-446655440001",
    "monitorableId": "550e8400-e29b-41d4-a716-446655440003",
    "monitorableIncidentId": "550e8400-e29b-41d4-a716-446655440002",
    "createdAt": "2024-01-15T10:31:01Z"
  },
  "createdAt": "2024-01-15T10:31:01Z"
}

Action types

These are the action types you receive on webhooks and when you list actions on an incident.

Type	Description
AGENCY_ANSWERED_CALL	The 911 center answered ADT's call
AGENCY_DISPATCH_ACKNOWLEDGED	The agency acknowledged ADT's dispatch request
AGENCY_DISPATCH_DECLINED	The agency declined to dispatch
AGENCY_NOTIFIED_FIRE_DEPT	ADT agent notified the fire department
AGENCY_NOTIFIED_MEDICAL	ADT agent notified emergency medical services
AGENCY_NOTIFIED_PATROL	ADT agent notified patrol
AGENCY_NOTIFIED_POLICE	ADT agent notified police
AGENT_ASSIGNED	ADT agent was assigned to the alarm
AGENT_CLOSED_INCIDENT	ADT agent closed the incident
ALARM_MESSENGER_CANCEL_REQUESTED	Alarm Messenger cancel was requested
ALARM_MESSENGER_VERIFIED	Alarm Messenger verified the alarm
DIALED_EMERGENCY_CONTACT	ADT agent dialed an emergency contact
DIALED_PRIMARY_CONTACT	ADT agent dialed the primary contact
ELECTRONIC_CANCEL	The incident was cancelled electronically, including before an agent is assigned
EMERGENCY_CONTACT_ANSWERED	An emergency contact answered
INCORRECT_VERBAL_PASSWORD	An incorrect verbal password was provided
LEFT_VOICEMAIL	ADT agent left a voicemail for the primary contact
NO_AGENCY_NOTIFICATION	The customer told ADT that no agency response was required
PRIMARY_CONTACT_ANSWERED	The primary contact answered
PRIMARY_CONTACT_NO_ANSWER	The primary contact did not answer
VERBAL_PASSWORD_ACCEPTED	A verbal password was accepted

Creating an incident

Create an incident when you detect a situation at a monitorable that ADT should handle. This route requires the monitorable-incident:write scope.

• POST /v1/monitorables/{monitorableId}/incidents — open an incident with one or more events

The request needs at least one event. Each event uses an event type that is enabled for the monitorable's type, and can carry media such as video clips:

{
  "observedAt": "2024-01-15T10:29:55Z",
  "events": [
    {
      "type": "INTRUSION",
      "observedAt": "2024-01-15T10:29:50Z",
      "media": [
        {
          "type": "CLIP",
          "url": "https://media.example.com/clips/front-door.mp4"
        }
      ]
    }
  ]
}

What happens when you create an incident:

1. Any earlier incident on the monitorable that is not CLOSED is closed. You receive a monitorable-incident:update webhook for it.
2. The new incident starts as OPEN. You receive a monitorable-incident:create webhook.
3. Each event is sent to ADT for monitoring, and you receive an event:create webhook for it.
4. When ADT starts working the alarm, its operator actions attach to your incident.

To choose the incident id yourself, pass a UUID in the id query parameter. Hyperion returns 409 if an incident with that id already exists.

The monitorable must not be INACTIVE or CANCELLED.

Adding events to an incident

Add an event when something new happens during an incident you already opened. This route requires the monitorable-incident:write scope.

• POST /v1/monitorables/{monitorableId}/incidents/{incidentId}/events — add one event to the incident

The request body is a single event, in the same shape as one entry in the events list when you create an incident. The response is the created event.

What happens when you add an event:

1. If the incident is RESOLVED, it goes back to OPEN and resolvedAt is cleared. You receive a monitorable-incident:update webhook.
2. The event is sent to ADT for monitoring, and you receive an event:create webhook for it.

Hyperion returns 400 if the incident is CLOSED, and 404 if the incident belongs to a different monitorable.

Updating an incident

Update an incident you own. This route requires the monitorable-incident:write scope.

• PATCH /v1/monitorables/{monitorableId}/incidents/{incidentId} — update the incident

Closing an incident

Close an incident when you are done with it after ADT resolved it. A closed incident cannot change again.

Send CLOSED as the status. You can add an optional reason of up to 255 characters:

{
  "status": "CLOSED",
  "reason": "Customer confirmed a false alarm"
}

What happens when you close an incident:

1. The incident moves from RESOLVED to CLOSED. closedAt is set, and reason is set if you sent one.
2. You receive a monitorable-incident:update webhook.
3. The response is the closed incident.

Hyperion returns 400 if the incident is still OPEN, because ADT must resolve it first. Closing an incident that is already CLOSED returns it unchanged, and you receive no webhook. Hyperion returns 404 if the incident belongs to a different monitorable.

When you create a new incident, Hyperion closes the earlier one for you without a reason.

Reading incidents

These routes require the monitorable-incident:read scope.

• GET /v1/monitorables/{monitorableId}/incidents — list incidents for the monitorable
• GET /v1/monitorables/{monitorableId}/incidents/{incidentId} — returns 404 if the incident belongs to a different monitorable
• GET /v1/monitorables/{monitorableId}/incidents/{incidentId}/actions — list operator actions on the incident
• GET /v1/monitorables/{monitorableId}/incidents/{incidentId}/events — list events linked to the incident; also requires the event:read scope