Register for WebPush Notifications

This API call allows for registering or updating of an account for transmission of standardized WebPush notifications (W3C WebPush, IETF RFC 8030). 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. If this method is called again for the given unique endpoint, any existing settings will be overwritten. To remove the notifications registered use Unregister WebPush Notifications.

Important Notes

  • Web Push Data encryption (RFC 8291) can be utilized for encrypting the message bodies.
  • To utilize VAPID (RFC 8292) authentication, retrieve the public key from the Get WebPush Service Options endpoint and provide the data to your invocation of PushManager::subscribe() call via the options::applicationServerKey value.
  • 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_updatedactivity_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.
  • To change the types of notifications just invoke this call again with the PushSubscription object retrieved by the HTML5 PushManager::getSubscription() function.

Permissions

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

Event Verification

All event notification calls are signed using VAPID (RFC 8292) for the server-to-server leg. VAPID signature is passed in the Authorization and Crypto-Key headers. The content is encrypted according to Web Push Data encryption (RFC 8291).

Event Body

The outer body uses RFC 8030 Payload Format. The inner body uses the regular Notification Events structure.

Language
Authentication
OAuth2