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

The following calls are related to subscription of events

• Register for Client Notifications
• Register for Server Notifications
• Get WebPush Service Options
• Register for WebPush Notifications
• Unregister WebPush Notifications

Notification content is always JSON.

JSON Event Body

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_created - Sent once after the initial Activity is created and the first analysis for Classifiers has been completed. The initial Activity meta-data is included in the notification.
• activity_updated - Sent zero or more times depending on the length of the Activity. The Classifier meta-data can change and is cumulative for items detected. Relevance Level can change from the initial activity_created event.
• activity_finished - Sent once and indicates that no further activity_updated events will happen. The meta-data is now finalized and calls to the Activities API functions such as Get Activity by Id, Get Activity DASH, Get Activity JPG File and Get Activity MP4 File are now idempotent.

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.

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:

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.

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.

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"
    }
}