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.

A monitorable can have only one active incident at a time. The incident stays open until an ADT agent clears it. After it is cleared, a later alarm can open a new incident.

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

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 premises, they tried dispatch, they cleared it.

The first action opens the incident. Later actions attach to the same incident. A clear action (AGENT_CLEARED_INCIDENT or ELECTRONIC_CANCEL) sets closedAt. Actions can still attach after the incident is closed.

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

Sample webhook payloads

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",
    "closedAt": null,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

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",
    "type": "DIALED_PREMISES",
    "occurredAt": "2024-01-15T10:31:00Z",
    "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
AGENT_ACCESSED	ADT agent accessed the alarm
AGENT_CLEARED_INCIDENT	ADT agent cleared the incident
AGENCY_DISPATCH_ATTEMPT	Agency dispatch was attempted
AGENCY_DISPATCH_CONFIRMED	Agency dispatch was confirmed
AGENCY_DISPATCH_DECLINED	Agency dispatch was declined
AGENCY_DISPATCH_NO_REFERENCE	Agency dispatch completed without a reference number
ALARM_MESSENGER_CANCEL_REQUESTED	Alarm Messenger cancel was requested
ALARM_MESSENGER_VERIFIED	Alarm Messenger verified the alarm
CALL_ENDED	The call ended
CONTACT_ANSWERED	A contact answered
DIALED_AGENCY	ADT operator dialed the agency
DIALED_CONTACT	ADT operator dialed a contact
DIALED_PREMISES	ADT operator dialed the premises
ELECTRONIC_CANCEL	The incident was cancelled electronically
INCORRECT_VERBAL_PASSWORD	An incorrect verbal password was provided
NO_AGENCY_NOTIFICATION	No agency was notified
PREMISES_ANSWERED	The premises answered
PREMISES_ANSWERING_MACHINE	The call reached an answering machine
PREMISES_NO_ANSWER	The premises did not answer
VERBAL_PASSWORD_ACCEPTED	A verbal password was accepted

Reading incidents

These routes require the monitorable-incident:read scope.

• GET /v1/monitorable-incidents — list incidents. Filter with monitorableId.
• GET /v1/monitorable-incidents/{incidentId}
• GET /v1/monitorable-incidents/{incidentId}/actions — list operator actions on the incident