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": "2019-11-18T09: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 base-64 encoded hash of the request body

Examples are available in our cronofy/notification-hmac-examples Github repository

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 has become disconnected and the user will need to reauthorize the affected calendar account. Profile Information gives current connection status for all profiles associated with a user.
  • 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 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.

In This Section

Search