Notification Channels

Introduction

Google Calendar Notification Channels provide a way for applications to receive real-time updates about changes to calendar events without continuously polling the Google Calendar API. This is achieved using webhooks, where Google sends notifications to a specified endpoint (webhook) whenever there are changes in the calendar events.

Purpose

The main purpose of Google Calendar Notification Channels is to enable applications to synchronize calendar data efficiently and respond promptly to changes such as event creation, updates, or deletions.

Where are we using it

In Google calendar extension for Scrims notification channels are registered when 1. a new calendar is created from the dashboard, 2. when Google calendars are read by the dashboard and 3. when Scrims calendar is attached with a calendar.

Note that it only generates a new notification channel if either it isn't already found or if it isn't expired. So on read we're executing the registration logic but it skips it as a channel is already registered and not expired yet.

Key Concepts

1. Watch Request:
   • To set up a notification channel, you initiate a "watch" request on a specific calendar using the Google Calendar API. This request includes details such as the type of notification (e.g., webhook), the endpoint where notifications should be sent, and optional parameters like time-to-live (TTL) for the channel.
2. Webhook Endpoint:
   • This is the URL of your application where Google will send notifications. It should be a publicly accessible HTTPS endpoint capable of receiving and processing POST requests.
3. Notification Payload:
   • When an event changes in the monitored calendar, Google sends a POST request to your webhook endpoint. The payload of this request contains information about the event that triggered the notification, such as event ID, summary, start time, end time, and any other relevant details.

Example Scenario

Let's illustrate with an example scenario:

Scenario: Setting Up a Notification Channel

1. Prerequisites:
   • You have a Google Cloud project with the Calendar API enabled.
   • OAuth 2.0 credentials (Client ID and Client Secret) are set up for authentication.
   • Your application has a webhook endpoint (https://yourapp.com/google/calendar/webhook) ready to receive notifications.
2. Generating a Notification Channel:
   • You use the Google Calendar API to initiate a "watch" request on a specific calendar. This request specifies:
     • The type of notification channel (e.g., webhook).
     • The address (URL) of your webhook endpoint (https://yourapp.com/google/calendar/webhook).
     • Optional parameters such as TTL to specify how long the channel should remain active.
3. Handling Notifications:
   • When a calendar event changes (e.g., created, updated, deleted), Google sends a POST request to your webhook endpoint (https://yourapp.com/google/calendar/webhook).
   • Your application processes this request, updating its internal state or taking actions based on the event data received.

Example Notification Payload

{
  "kind": "calendar#event",
  "id": "abcdef123456",
  "status": "confirmed",
  "summary": "Team Meeting",
  "description": "Discuss quarterly goals",
  "location": "Conference Room A",
  "start": {
    "dateTime": "2024-07-19T09:00:00-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2024-07-19T10:00:00-07:00",
    "timeZone": "America/Los_Angeles"
  }
}

Conclusion

Google Calendar Notification Channels streamline the process of staying updated with calendar events in real-time. By setting up a webhook and initiating a notification channel, your application can efficiently manage and respond to changes in Google Calendar events, ensuring data synchronization and timely updates.