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
, ormotion_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 youreventTypes
.
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