Google Calendar

Prerequisites

1. A Google Cloud Console project
2. Google Calendar API enabled on that project
3. OAuth 2.0 credentials of type "Web application"
4. For near-real-time inbound sync, the app reachable at a public HTTPS URL on a domain you have verified with Google (Google will not create a change channel that points at a private address, a plain-HTTP address or an unverified domain)
5. The Laravel scheduler cron, which drives the inbound poll and the channel renewals

Setup Instructions

1. Google Cloud Console Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
   • Go to "APIs & Services" > "Library"
   • Search for "Google Calendar API"
   • Click on it and press "Enable"

2. OAuth Consent Screen and Scopes

Configure the consent screen and add the scopes Event Schedule requests. Anything missing here shows up later as a failed sync rather than a failed sign-in.

• https://www.googleapis.com/auth/calendar.events to create, update and delete events
• https://www.googleapis.com/auth/calendar.readonly to list calendars and read events for inbound sync
• openid, email and profile to identify the connecting account

While the project is in testing mode, add each account that will connect a calendar as a test user. Event Schedule always requests offline access and forces the consent prompt, so a refresh token is issued on every connect.

3. OAuth 2.0 Credentials

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "OAuth 2.0 Client IDs"
3. Choose "Web application" as the application type
4. Add authorized redirect URIs:
   • For development: http://localhost:8000/google-calendar/callback
   • For production: https://yourdomain.com/google-calendar/callback
5. Save the credentials and note down the Client ID and Client Secret

4. Environment Configuration

Add the following environment variables to your .env file:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=https://yourdomain.com/google-calendar/callback
GOOGLE_WEBHOOK_SECRET=a_long_random_string

Variable Reference

5. Scheduler Cron

Inbound polling and channel renewal run through the Laravel scheduler, so the standard cron entry has to be in place:

* * * * * php artisan schedule:run

Features

How Sync Works

1. Connect an account: Each user connects their own Google account from Settings → Google Settings, in the Google Calendar block. The tokens are stored on that user record
2. Pick a calendar and a direction: The schedule owner chooses one of the connected account's calendars and a sync direction on Integrations → Google Calendar of the schedule edit page. The setting belongs to the schedule, so two schedules on the same account can behave differently
3. Outbound: Publishing, editing, cancelling or deleting an event pushes the change to the selected calendar, with no extra step
4. Inbound: Google change notifications post to the webhook endpoint, and Event Schedule reads the changes with an incremental sync
5. Polling fallback: The 15-minute google:sync command catches anything the notifications miss, and is the only inbound path on installs without a public URL
6. Channel renewal: The daily google:refresh-webhooks command replaces change channels within three days of expiring

Sync Direction

Each schedule picks one of four options. Saving the schedule is what applies the choice and sets up the change channel.

Event Information Synced

A Google Calendar entry created by Event Schedule carries:

• The event name, as the Google event title
• The event description. If the schedule has a Calendar Description Template set on Integrations → Advanced, the rendered template is sent instead (see the available variables). On an update with no template and an empty description, no description is sent, so notes you typed on the Google copy survive
• Start and end times in the schedule's timezone. The end is the start plus the event duration, and two hours when the event has no stored duration
• Location, taken from the venue's best available address. Events with no venue are sent without a location
• Google visibility: public for normal events, private for unlisted ones

Importing From Google

Inbound sync expands Google's recurring events first, so each occurrence arrives as its own event. Imported events:

• Arrive already approved, and use the schedule's slug pattern and default category
• Take their name, description, start time and duration from the Google entry. The description is converted from HTML to Markdown
• Convert the Google location into a venue, reusing one of your existing venues when the name or address matches and creating one when nothing matches
• Are matched to an existing event by name and start time when there is no stored mapping yet, so an event you pushed out does not come back as a duplicate

Per-Event Sync Status

The Google Calendar section of the event edit page shows the state of this event on the calendar of the schedule you are editing it under:

When an Event Is Deleted in the Connected Calendar

Schedules that sync inbound also choose When an event is deleted in the connected calendar, shown right under the sync direction once the direction is From Google Calendar or Bidirectional Sync. The setting is shared with the Outlook Calendar integration, so changing it on either tab changes it for both.

Only a real deletion in Google Calendar triggers the policy, and only through the incremental sync, so the schedule needs at least one completed inbound sync first.

If the deleted copy belonged to a schedule that shares the event with others, that schedule is simply detached and the event stays intact for everyone else.

Personal Calendar Sync for Members

A team member who is not the schedule owner sees a Sync to My Calendar block on the schedule's Google Calendar tab. Choosing one of their own calendars mirrors the schedule's events into it, in addition to whatever the owner has configured, and the member gets the same create, update and delete operations even when the owner has left the schedule on No Sync. Turning it back off removes the copies the member received.

The member needs their own connected Google account, and the block has its own Save button, separate from the schedule form. Turning it on does not backfill: events already on the schedule reach the member's calendar the next time they are edited. This is a Google-only feature, since the Outlook and CalDAV integrations sync the owner's calendar only. Adding team members beyond the owner is an Enterprise feature on the hosted service, and a selfhosted install resolves to Enterprise.

Real-Time Sync and Polling Fallback

• Saving a schedule with an inbound direction creates a Google change channel that posts to the webhook endpoint, so calendar edits show up within moments. If the channel cannot be created the save still succeeds, the failure is logged, and inbound changes fall back to the poll
• The 15-minute google:sync command polls for changes as a fallback, and is the main path on installs with no public URL. It uses the schedule owner's connected account
• The daily google:refresh-webhooks command replaces channels that are within three days of expiring
• Inbound sync is incremental: Event Schedule stores Google's sync cursor, so each run fetches only what changed. If Google rejects the stored cursor, which happens after a long gap or a calendar switch, one full sync runs to rebuild it
• The first full sync covers a window from 30 days ago to 365 days ahead
• Inbound work is serialized per schedule, so the webhook and the poll cannot import the same event twice

Usage

Step by Step

Automatic Sync

Once a schedule pushes to Google, its events are synced automatically when they are:

• Published, whether that is a new event or a draft you just published
• Edited, which updates the existing Google entry in place
• Deleted, cancelled or turned back into a draft, which removes the copy from the calendar. Restoring a cancelled event puts it back

Drafts are never pushed, so an event only reaches the calendar once it is published. Members with personal calendar sync receive the same create, update and delete operations even when the owner has not turned on sync for the schedule.

For Developers

Sync Helpers on the Event Model

Outbound sync and status checks go through the Event model:

// Push to every schedule that syncs to Google, plus members with personal sync
$event->syncToGoogleCalendar('create'); // or 'update', 'delete'

// Is there a Google copy for a given schedule?
$event->isSyncedToGoogleCalendarForRole($role->id);
$event->isSyncedToGoogleCalendarForSubdomain($subdomain);

// 'not_connected', 'not_synced' or 'synced'
$event->getGoogleCalendarSyncStatus($user, $role->id);

How the Work Is Dispatched

The mapping between an event and its Google copy lives in the calendar_syncs table, one row per user, event and schedule, together with the calendar the copy was created on.

• SyncEventToGoogleCalendar performs one create, update or delete. Saving an event runs it inline, so the calendar is up to date by the time the save finishes and a queue worker is not required
• ForceResyncGoogleCalendar backs the "Resync to Google Calendar" button and is queued. It handles a small batch of events per run and dispatches a follow-up while any remain, so a large schedule finishes across several runs instead of timing out
• Inbound sync is serialized per schedule with a lock, so the webhook and the 15-minute poll cannot import the same event twice

API Endpoints

These are the application's own session-authenticated routes, not part of the public REST API. Every route except the two webhook routes requires a signed-in user with a verified email address. The webhook routes are public, and are authenticated by the channel token instead.

Scheduled Commands

These Artisan commands keep inbound sync and the change channels healthy:

Troubleshooting

Common Issues

Logs

Sync operations are logged in the application logs. Check storage/logs/laravel.log for detailed information about sync operations, and storage/logs/scheduler.log for the scheduled sync and channel-renewal runs.

Security Considerations

1. Token Storage: Google access and refresh tokens are stored per user and encrypted at rest with the install's APP_KEY, and they are hidden from the model's serialized output
2. Scope Limitation: Only the calendar scopes the integration needs are requested, plus openid, email and profile to identify the account
3. OAuth State Check: The connect flow carries a random state value that is verified on the callback, so a forged callback is rejected
4. Webhook Authentication: GOOGLE_WEBHOOK_SECRET is the channel token Google echoes back, and mismatched notifications are rejected. Both webhook routes are rate limited
5. User Authorization: Users can only sync events belonging to schedules they are a member of, and only the schedule owner can trigger a full resync
6. Token Refresh: Access tokens are refreshed automatically before each call that needs one
7. Clean Disconnect: Disconnecting removes the change channels and turns sync off for the schedules the user owns, clears their sync cursors, and deletes the stored tokens, the user's event mappings and their calendar selection on every schedule they belong to. It does not delete anything already on the Google calendar
8. Audit Trail: Connecting, disconnecting, syncing a schedule and toggling personal member sync are all written to the audit log
9. Secrets in .env: Keep the client secret and webhook secret in .env, and never commit them to source control