Notification Events

The Notification Events subsystem is responsible for pushing data out to clients when events occur.

The following calls are related to subscription of events

Notification content is always JSON.

JSON Event Body

Name

Type

Description

accountId

string

The Account Id involved.

eventType

string

Which event payload is contained in the eventData field. One of:

  • activity_created
  • activity_updated
  • activity_finished
  • activity_deleted
  • motion_started
  • motion_ended
  • accessory_added
  • accessory_deleted
  • accessory_settings_changed
  • service_plan_changed
  • summary_created
  • firmware_update_started
  • firmware_update_progress
  • firmware_update_completed
  • account_deleted

eventData

object

The event specific data payload defined below.

userData

any

The userData supplied in the Register for Server Notifications call. If no userData was supplied this field will not be present.

Event Data Payloads

Each eventType has a specific payload format in the eventData field.

activity_created, activity_updated, and activity_finished

These events all contain the same object as you get from Get Activity by Id with the addition of an accessoryId field for the Accessory involved. All of these events are propagated in near real-time with a delay between occurrence and transmission ranging from several seconds to one minute. When receiving these events, there is no need to call Get Activity by Id, as the same data is present already in the eventData field.

activity_deleted

This event indicates that the user has performed an early delete of an Activity . After this event is received, calls to the Activities API will fail with a 404 - Not Found. Media related to the Activity has already been purged when this event gets propagated.

Name

Type

Description

accessoryId

string

The Accessory Id involved.

activityId

string

The Activity Id involved.

motion_started and motion_stopped

These events require the rarely granted Permissions scope of circle:notifications_motion.

These are raw, unfiltered and possibly high frequency events indicating that the camera has detected some kind of motion is in progress. Since motion events are unprocessed, an Activity may not be created if the Classifiers engine later determines there is no Relevance Level for it. These events are propagated in real-time with a delay of 0 to 4 seconds from actual occurrence. A single motion_stopped event will always be sent if a motion_started event has occurred regardless if an Activity was created. The payload for these events is an object containing the following keys:

Name

Type

Description

accessoryId

string

The Accessory Id involved.

timestamp

string

The originating UTC Timestamp at the Accessory that the event occurred. The offset from wall-clock time can be used to determine overall event propagation delay if needed.

accessory_added

This event contains the same object as you get from Get Accessory by Id and is triggered from an invocation of Create Accessory. Since the process of creating an Accessory is asynchronous and involves BLE setup, only the Accessory Id in the return set is considered valid. As the camera completes its WiFi setup and configuration, you will receive accessory_settings_changed events with valid contents. An accessory is not considered fully setup until the firmwareVersion field is populated with a non-empty value.

accessory_deleted

This event contains the following object with just an "accessoryId" field for the Accessory involved. This event is triggered from an invocation of Delete Accessory by Id.

Name

Type

Description

accessoryId

string

The Accessory Id involved.

accessory_settings_changed

This event means that a client (including yours) has changed a setting on the Accessory via the Set Accessory Config by Id call. This event contains the same object as you get from Get Accessory by Id.

service_plan_changed

This event contains the same object as you get from Get Accessory by Id and indicates that the Service Plan Features are now different.

summary_created

This event contains the bare summary object as defined in Get Summary by Id. When this event is received the Summary state is now processed and ready to be viewed or downloaded.

firmware_update_started, firmware_update_progress, firmware_update_completed

If these events are received, but were initiated by your client, it means another party initiated the firmware update. You can then track the progress

  • firmware_update_started - This indicates the firmware update process has begun.
  • firmware_update_progress - This reports a change in the firmware download percentage progress. You may not receive this event if the download goes very fast. You must handle the race condition between this event and accessory_settings_changed when the Accessory goes offline to reboot and finish the update.
  • firmware_update_completed - Sent once and indicates that the firmware update has ended. If the process goes fast, this may be the only event received. You must handle the race condition between this event and accessory_settings_changed when the Accessory comes back online after its reboot.

Name

Type

Description

accessoryId

string

The Activity Id involved.

completionStatus

string

One of the following which indicates success or failure:

InProgress - The process is still going on. This is the value during firmware_update_started and firmware_update_progress events.
OK - The update completed successfully.
BatteryLow - The battery was too low after the download completed to finish.
Cancelled - The camera cancelled the update most likely because something else caused a reboot of the camera.
DownloadTimeout - The download timed out due to taking too long and the operation aborted
DownloadError - The download failed or the file was corrupted after downloading. This is likely caused by a proxy or other network issue.
InstallError - The firmware was not able to be installed on the device, and the device has come back online.
InstallTimeout - The Accessory never returned online after rebooting to complete the update.
Offline - The Accessory went offline before the download/install completed and the update has failed. This typically occurs if the power is removed during the download or install phase. This state can take several minutes to propagate depending on how uncleanly the camera went away.

downloadProgress

integer

This is a value from 0 to 100. This field is only valid in the firmware_update_started and firmware_update_progress events.

firmwareId

string

The Firmware Version Id being installed. You can match this to data from Get Firmware by Model Number.

version

string

The user visible firmware version being installed. This is the same as the version field returned in Get Firmware by Model Number.

account_deleted

This event is sent when an account is deleted from the Circle system. This is a rare event, but typically occurs due to the GDPR deletion requests. This event is propagated to all receivers even if it wasn't specified in the eventFilter for your registration. You will receive this event after receiving individual accessory_deleted events. After the Circle servers propagate this event, all Notification registration will be automatically deleted and active WebSockets connections will be closed. There is no need for your client to invoke Unregister Server Notifications or Unregister WebPush Notifications. There is no additional payload in this event as the main payload already contains accountId.

Examples

{
    "accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
    "eventType": "activity_created",
    "eventData": { ... }
}
{
    "accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
    "eventType": "activity_created",
    "eventData": { ... }
    "userData": {
        "foo": "bar"
    }
}
{
    "accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
    "eventType": "account_deleted",
    "eventData": {}
    "userData": {
        "foo": "bar"
    }
}