Web push notifications are messages sent from an application to a user's device, even when the user is not actively browsing the site. They enable real-time communication with users, allowing websites to deliver timely updates, alerts, and personalized content. Push notifications are an effective alternative to polling, enabling the server to proactively send data to the client when new information is available, reducing unnecessary network traffic and server load.

To understand this more, lets see how Cronofy, a scheduling infrastructure layer with calendar APIs, uses push notifications to inform you once a change has occurred so that you can then call the API and retrieve the changes.

The result of this is being able to keep your view of the data up-to-date while only performing updates when there has been genuine changes to it.

Keeping your application up to date with an end user’s calendar using Push Notifications

First, if you haven’t already, create a developer account with Cronofy (it’s free for devs 💫). You can find the getting started guide for building scheduling functionality into your application which will be good context to follow along for the rest of the guide.

In order to be certain that the user’s events stay up to date in your system, you can utilise Push Notifications, Read Events, and regular weekly syncs.

Step 1. Make the Create Push Notifications Channel request in Postman.
Example request

POST /v1/channels HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json; charset=utf-8

{
  "callback_url": {CALLBACK_URL},
  "filters": {
    "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
    "only_managed":false}
}

Step 2. Create, move, or delete an event in Google Calendar to trigger a change notification.

Step 3. See the ‘change’ push notification come through.
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-10-23T09:24:16Z"
  },
  "channel": {
    "channel_id": "chn_54cf7c7cb4ad4c1027000001",
    "callback_url": {CALLBACK_URL},
    "filters": {
      "calendar_ids": ["cal_n23kjnwrw2_sakdnawerd3"],
      "only_managed":false
    }
  }
}

Note that ‘change’ notifications will include a changes_since parameter that can be used as the last_modified parameter for a subsequent Read Events request, allowing integrators to only have to query for data that changed since the last observed change within Cronofy.

Step 4. Run a Read Events call on the associated calendar_id to poll for the changes made that triggered the notification.
Example Request

GET /v1/events?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

An important caveat in this context is the fact that every API will have different sync windows which will determine the balance between the frequency of your application performing sync operations (potentially impacting performance) and how current the data remains (impacting accuracy and responsiveness). In Cronofy’s case, sync windows start at 42 days in the past and ends 201 days into the future.

To avoid overloading the notification channel, a Push Notification will not be triggered when an event becomes visible due to the sync window moving. As a result, the event will not get synced unless you schedule regular polling of the calendar to catch any events moving into the sync window. To sync these events, you can set up a manual Read Events call towards the end of the sync window and catch the events far in advance. For example, a weekly request polling for events before the end of our default sync window can look like this:

GET /v1/events?from={194_days_from_today}&to={201_days_from_today}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}

When leveraging push notifications in your application, consider the frequency of running syncs to ensure full coverage of event changes are captured. In the case of building calendar push notifications, we recommend running a weekly or daily sync by carrying out a read events call for all events for the calendar. While the other steps will ensure complete coverage, this occasional full sync provides robustness.

You’ve now learnt how to utilize push notifications in the context of calendar event changes but the principals covered here can also be applied to other contexts such as profile disconnections, initial sync completion after an end-user connects their calendar to your platform for the first time, or when they submit a GDPR deletion request.