Push Notifications

Push notifications provide a mechanism to lazily retrieve information about an account in order to avoid the need for API clients to create polling infrastructure.

Rather than having to frequently check for changes, instead we inform you when changes have occurred so that you can retrieve them.

This enables you to keep your data as fresh as possible whilst using minimal computing resources.

Push notifications are available for all calendar providers, not just those that support them natively.

Example Push Notification Request #

POST {CALLBACK_URL_PATH} HTTP/1.1
Host: {CALLBACK_URL_HOST}
Content-Type: application/json; charset=utf-8
Cronofy-HMAC-SHA256: {Base64(HmacSHA256(body_bytes, CLIENT_SECRET))}

{
  "notification": {
    "type": "change",
    "changes_since": "2024-12-17T09:24:16Z"
  },
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
      "only_managed": false
    }
  }
}

Once a push notification channel has been created the callback URL specified will receive push notifications for changes to the user’s account and calendars.

These will come in the form of POST requests with a Content-Type of application/json; charset=utf-8.

Request headers #

Cronofy-HMAC-SHA256  #

Can optionally be used to verify that the notification was sent by Cronofy.

This HMAC uses the SHA256 algorithm, keyed with the application's client secret, to generate a Base64 encoded hash of the request body.

When an application has multiple active client secrets, a value is generated for each active secret, separated by commas. For example:

 Cronofy-HMAC-SHA256: {HMAC_FROM_SECRET_1},{HMAC_FROM_SECRET_2}
 

Examples are available in our cronofy/notification-hmac-examples Github repository, and our API libraries include methods to verify this header.

Request parameters #

notification.type  #

The type of change this notification is for.

There are currently five types of notification but your code should be tolerant of others, by ignoring them, so if more are introduced in future your integration will not fail.

Current types

• verification sent after a channel is created to test that the specified callback URL is valid
• change signifies that a change has occurred to the user’s events so you should make a request to fetch those changes
• profile_disconnected signifies that one or more of the user’s calendar profiles have become disconnected and the user will need to reauthorize the affected account(s).
  Note that this notification will not be triggered until Cronofy attempts to access the profile in question, such as when trying to create an event over the API. It is at this point that we will invalidate the OAuth token and send this notification.
  The current state of a users profiles can be found via a call to UserInfo; the users calendar profiles can be found under the ["cronofy.data"]["profiles"] key in the response.
• conferencing_profile_disconnected signifies that one or more of the user’s conferencing profiles have become disconnected and the user will need to reauthorize the affected account(s).The current state of a users profiles can be found via a call to UserInfo; the users conferencing profiles can be found under the ["cronofy.data"]["conferencing_profiles"] key in the response.
• profile_initial_sync_completed signifies that the initial sync of the user’s calendar events has completed, you may wish to perform an additional sync when receiving this to ensure you have seen all their events. Note that you will not receive this notification if the initial sync completed before the channel was created.
• gdpr_requested signifies that the account has requested that their details are removed from our systems as part of the GDPR right to be forgotten.

notification.changes_since  #

The Time that the last change was seen. This will be returned in UTC.

This is only sent as part of a change notification and may be used as the last_modified parameter for a subsequent Read Events request.

channel.channel_id  #

The ID of the channel that triggered the notification.

channel.callback_url  #

The URL of the channel that triggered the notification.

channel.filters  #

Any non-default filters that were specified for the channel.

Expected response #

A successful response must have a response code in the 2xx range and be returned within 5 seconds.

Therefore, anything that takes longer than 5 seconds to respond, or responds with a code not in the 2xx range will be treated as if it has failed.

We will continue to attempt to send the push notification for 24 hours. If no notifications succeed during this period then it is assumed that the channel is no longer valid and so the channel will be closed automatically and no further push notifications will be sent.