> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar Webhook Setup Guide

> Configure Google Calendar to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/googlecalendar#getting-started) on the Google Calendar connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Automatic notification channels</h2>

  <p>StackOne creates and manages the Google Calendar notification channels automatically when the account is connected, and stops them when the account is disconnected. You don't need to set anything up in Google Calendar or the Google Cloud Console.</p>

  <Steps>
    <Step title="Select events in StackOne">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Enable the webhook events you want on the Google Calendar connector in StackOne. Google Calendar watches one collection per notification channel, so StackOne creates one channel for each selected event.</p>
      </div>
    </Step>

    <Step title="Check scope requirements">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each event needs read access to the collection it watches. The connector's default scope, `https://www.googleapis.com/auth/calendar`, covers every event. If you set narrower scopes on the StackOne Connector profile, include at least one of these per event:</p>

        <ul>
          <li><strong>Events Changed</strong>: `https://www.googleapis.com/auth/calendar.events.readonly`, `https://www.googleapis.com/auth/calendar.events` or `https://www.googleapis.com/auth/calendar.readonly`</li>
          <li><strong>ACL Changed</strong>: `https://www.googleapis.com/auth/calendar.acls.readonly` or `https://www.googleapis.com/auth/calendar.acls`</li>
          <li><strong>Calendar List Changed</strong>: `https://www.googleapis.com/auth/calendar.calendarlist.readonly`, `https://www.googleapis.com/auth/calendar.calendarlist` or `https://www.googleapis.com/auth/calendar.readonly`</li>
          <li><strong>Settings Changed</strong>: `https://www.googleapis.com/auth/calendar.settings.readonly` or `https://www.googleapis.com/auth/calendar.readonly`</li>
        </ul>
      </div>
    </Step>

    <Step title="Reconnect to renew expired channels">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Google ends every notification channel 30 days after it is created, and StackOne does not create replacements on its own. When events stop arriving, reconnect the account in StackOne Hub. StackOne stops the old channels and creates new ones for the selected events.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Google Calendar events can be enabled. Only events selected in StackOne get a notification channel, and Google Calendar does not deliver changes for collections that are not watched.</p>

  <Steps>
    <Step title="Calendar events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on the connected user's primary calendar.</p>

        <ul>
          <li><strong>Events Changed</strong> (`events.changed`) — Fired when an event on the user's primary calendar is created, updated, or deleted</li>
          <li><strong>ACL Changed</strong> (`acl.changed`) — Fired when a sharing rule on the user's primary calendar is created, updated, or deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="User events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on the connected user's calendar list and settings.</p>

        <ul>
          <li><strong>Calendar List Changed</strong> (`calendarList.changed`) — Fired when a calendar is added to, changed in, or removed from the user's calendar list</li>
          <li><strong>Settings Changed</strong> (`settings.changed`) — Fired when one of the user's Google Calendar settings changes</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Google Calendar delivers events to StackOne.</p>

  <Steps>
    <Step title="Notifications carry no change details">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Google Calendar notifications have no body. Each one says only that the watched collection changed; it does not say which item changed or how. Fetch the changes with the matching list action.</p>

        <ul>
          <li><strong>Events Changed</strong>: call `list_events` on the primary calendar with a `syncToken`.</li>
          <li><strong>ACL Changed</strong>: call `list_acl` on the primary calendar.</li>
          <li><strong>Calendar List Changed</strong>: call `list_calendar_list` with a `syncToken`.</li>
          <li><strong>Settings Changed</strong>: call `list_settings` with a `syncToken`.</li>
        </ul>
      </div>
    </Step>

    <Step title="Primary calendar only">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p><strong>Events Changed</strong> and <strong>ACL Changed</strong> watch the user's primary calendar. Changes on secondary or shared calendars are not delivered.</p>
      </div>
    </Step>

    <Step title="Event payload">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each event's ID combines the channel ID and Google's message number (`channelId:messageNumber`). The event data holds the notification headers: resource state, channel ID, resource ID, resource URI, message number, and the channel's expiry date.</p>

        <ul>
          <li>Google does not guarantee delivery of every notification, so run a periodic sync as a fallback.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.