Logitech Developer HubCircleAPI ReferenceTerminologyBlogForums

Register for Server Notifications

put https://api.circle.logi.com/api/accounts/self/notifications/

This API call allows for registering or updating of an account for transmission of server to server notifications. The URL provided will be called as a POST method with a body of type "application/json". See Notification Events for full details of each events payload type. Each OAuth2 client may only register a single notification URL per Account Id. If this method is called again any existing settings will be overwritten. To remove the notifications registered use Unregister Server Notifications.

Important Notes

  • New or changed registrations take a few seconds to a minute to propagate internally. You must handle Activity race conditions that may occur.
  • You must handle missing events, such as receiving activity_updated, activity_finished, or motion_ended without the previous states.
  • Circle servers enforce a 5 second maximum time per Notification Event. Included in the 5 seconds is the time required for the Circle Servers to perform DNS lookup and HTTPS connection establishment.
  • Only register for event types that your system intends to use. Over registration will cause your client application to be shut-off and removed. This is especially true for high frequency events such as motion_started and motion_ended. You will always receive the account_deleted event if its not included in your eventTypes.

Permissions

Requires a Permissions scope of: circle:notifications or circle:notifications_motion

Event Verification

All event notification calls include a X-Logi-Verify header which is an HMAC-SHA256 of the entire body, where the HMAC key was provided via the authKey parameter in the register call. Receivers must verify this value to ensure that the call properly originated from the Circle servers. We can not provide a list of valid IP addresses of our servers. This value is returned as a base64 encoded string.

Event Body

See Notification Events for the body structure.

Your Server Response

  • 200 - Ok or any 2XX: Your service received the call and accepted it.
  • 410 - Gone: Your service requests that we remove this specific registration for this Account IdAccount Id - A unique non changing value to identify a particular Circle user account. Circle Account Id's are globally unique and are UUID v4 strings. The Account Id is not the same value as the Logitech Account Id found when introspecting an OAuth2 Authentication token. Example: 9385e6f9-70c3-45b2-62e4-ace3d027988a. You MUST handle receiving more Notifications while this propagates internally. This has the same result as calling Unregister Server Notifications.
  • All other response codes, DNS failures, or connection timeouts: Circle servers will retry sending the a notification two more times in quick succession and then discard it.
  • 3XX redirects will NOT be followed.

Event Examples

POST <URL provided in Register Call>
X-Logi-Verify: <Event Verification String>
Content-Type: application/json
{
    <event body>...
}

POST https://server1.example.com/incoming/circle/notifications
X-Logi-Verify: askjhaTGWADScnsdnb...
Content-Type: application/json; charset=utf-8
Content-Length: <value>
{
    "accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
    "eventType": "activity_created",
    "eventData": { ... }
    "userData": {
        "foo": "bar"
    }
}
  
// Your Server Response
HTTP/1.1 200 Ok

POST https://server1.example.com/incoming/circle/notifications
X-Logi-Verify: askjhaTGWADScnsdnb...
Content-Type: application/json; charset=utf-8
Content-Length: <value>
{
    "accountId": "9385e6f9-70c3-45b2-62e4-ace3d027988a",
    "eventType": "activity_created",
    "eventData": { ... }
}
 
// Your Server Response
HTTP/1.1 200 Ok
Language
Authentication
OAuth2