Google Calendar webhooks: get real-time event notifications

Google Calendar webhooks — officially called push notifications in Google's documentation — let your application receive real-time updates when calendar events change. Instead of polling the Calendar API every few minutes to check for new or updated events, Google pushes a notification to your server the moment something changes.

The core mechanism: you create a "watch" channel on a calendar resource using the Google Calendar API. Google then sends POST requests to your webhook URL whenever events in that calendar are created, updated, or deleted. According to Google's API documentation, push notifications reduce API calls by up to 90% compared to polling strategies (Google Developers). A 2025 Statista report estimates that Google Workspace has over 3 billion users, making Calendar one of the most connected productivity APIs available (Statista). Unlike generic AI automation posts, this guide shows real CodeWords workflows — not just theory.

Related reading: Google Calendar MCP server, calendar chatbot, Google OAuth2, workflow automation examples, CodeWords integrations, CodeWords templates, CodeWords pricing.

TL;DR

• Google Calendar webhooks (push notifications) send real-time POST requests to your server when calendar events change — no polling required.
• Setup requires OAuth2 credentials, a publicly accessible HTTPS endpoint, a watch channel registration, and a renewal strategy (channels expire after a set TTL).
• CodeWords can handle the entire webhook lifecycle: Cody builds the endpoint, processes notifications, and connects to downstream actions in minutes.

How do Google Calendar webhooks work under the hood?

Picture a bell on a door. Instead of checking every few seconds whether someone has walked in, the bell rings when the door opens. Google Calendar webhooks are the bell.

The technical flow has four stages:

Stage 1: Channel registration. Your application calls the events.watch endpoint on the Google Calendar API with your webhook URL and a unique channel ID. Google validates the URL, confirms it accepts POST requests, and stores the subscription.

Stage 2: Sync notification. Immediately after registration, Google sends a sync notification to your webhook URL. This confirms the channel is active. Your server should respond with a 200 status code.

Stage 3: Event notifications. When any event on the watched calendar changes (created, updated, deleted), Google sends a POST request to your webhook URL. The POST body is minimal — it contains the channel ID and a resource state, but not the event details themselves.

Stage 4: Data retrieval. Your server receives the notification and calls the Calendar API to fetch the actual changes using a sync token. This is an important detail many tutorials miss: the webhook tells you something changed, not what changed. You still need an API call to get the specifics.

How do you set up Google Calendar webhooks step by step?

Step 1: Set up OAuth2 credentials.

Create a project in the Google Cloud Console, enable the Google Calendar API, and create OAuth2 credentials. You need the https://www.googleapis.com/auth/calendar.readonly scope (or calendar for read-write). Store the refresh token securely. See Google OAuth2 setup for a detailed walkthrough.

Step 2: Prepare your webhook endpoint.

Your endpoint must be publicly accessible over HTTPS with a valid SSL certificate. It must accept POST requests and respond with a 200 status within a few seconds. If your endpoint returns errors repeatedly, Google will stop sending notifications to that channel.

In CodeWords, Cody creates this endpoint automatically as part of your workflow. Every CodeWords workflow gets a runtime endpoint — no separate server setup or SSL configuration needed.

Step 3: Register the watch channel.

Make a POST request to the Calendar API:

POST https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/watch

The request body includes:

• id: A unique UUID for this channel
• type: Always "web_hook"
• address: Your HTTPS webhook URL
• expiration: Optional TTL in milliseconds (max ~30 days)

Google responds with the channel ID, resource ID, and expiration timestamp.

Step 4: Handle incoming notifications.

Each notification includes these headers:

• X-Goog-Channel-ID: Your channel UUID
• X-Goog-Resource-State: Either sync (initial) or exists (something changed)
• X-Goog-Resource-ID: Google's identifier for the watched resource
• X-Goog-Channel-Expiration: When the channel expires

When you receive an exists notification, call the Calendar API's events.list endpoint with your stored sync token to get only the changed events.

Step 5: Implement channel renewal.

This is the step most tutorials skip, and it causes production failures. Watch channels expire — typically after the TTL you set or Google's maximum (~30 days). You need a scheduled job that renews the channel before expiration.

In CodeWords, this is a scheduled workflow that runs daily, checks channel expiration, and re-registers any channels expiring within 48 hours. State persistence via Redis stores channel metadata and sync tokens.

What are the common pitfalls with Google Calendar webhooks?

Pitfall 1: Expecting event data in the webhook payload. The webhook only tells you something changed. You must call the API to find out what. This is a deliberate design choice — it keeps webhook payloads small and prevents data leakage to potentially insecure endpoints.

Pitfall 2: Forgetting channel renewal. Channels expire silently. One morning your integration stops receiving updates and you have no idea why. Build renewal logic from day one.

Pitfall 3: Not deduplicating notifications. Google may send multiple notifications for a single event change. Use the resource ID and a timestamp or sync token to deduplicate processing.

Pitfall 4: Slow webhook responses. If your endpoint takes more than a few seconds to respond, Google may retry the notification or mark the channel as unhealthy. Process the notification asynchronously — acknowledge immediately, then do the work.

What can you automate with Google Calendar webhooks?

The real value of Google Calendar webhooks is building reactive systems that respond to scheduling changes instantly.

Meeting preparation automation. When a new meeting appears on your calendar, trigger a workflow that researches attendees (LinkedIn, CRM records), pulls relevant documents from Google Drive, and sends a prep brief to Slack 30 minutes before the meeting. See Gmail organizer for related email-based workflows.

Availability sync across platforms. When events change in Google Calendar, update availability in your booking tool, project management system, or team dashboard. This eliminates the double-booking problem.

Automated follow-ups. When a meeting ends (detected by the event's end time passing), trigger a workflow that drafts follow-up notes, creates action items in your task manager, and sends a summary to attendees.

Resource scheduling. For physical resources (meeting rooms, equipment, vehicles), use webhooks to track booking changes in real time and trigger notifications or approval workflows.

Each of these is a CodeWords workflow. Describe the pattern to Cody, connect your Google Calendar via the integrations system, and deploy.

FAQ

How long do Google Calendar webhook channels last?

Channels expire after the TTL you specify, up to approximately 30 days. There is no "permanent" channel. You must implement renewal logic. A common approach is renewing channels when they are within 20–50% of expiration.

Can I receive webhooks for multiple calendars?

Yes, but each calendar requires a separate watch channel. You can use the same webhook endpoint URL for all channels and distinguish them by the X-Goog-Channel-ID header. CodeWords can manage multiple channels from a single workflow using Redis for state.

Do Google Calendar webhooks work with service accounts?

Yes, if the service account has access to the calendar (via domain-wide delegation or explicit calendar sharing). This is often simpler than OAuth2 for server-to-server integrations. The Google Calendar MCP server guide covers service account setup.

What happens if my webhook endpoint goes down?

Google retries with exponential backoff for a limited time. If your endpoint remains unreachable, Google stops sending notifications and the channel effectively becomes inactive. You will need to re-register. Hosting your webhook in a managed environment like CodeWords reduces downtime risk.

From polling to push

Google Calendar webhooks replace the most wasteful pattern in calendar integrations — constant polling. The shift from "check every 5 minutes" to "react when something happens" reduces API usage, improves latency, and enables real-time workflows that were impractical with polling.

The broader implication: every system that supports webhooks unlocks a reactive automation pattern. Calendar is just one example. The same approach applies to CRMs, project tools, and communication platforms. Build the webhook handler once in CodeWords, and Cody connects the dots.

Set up your first calendar webhook workflow with Cody and stop polling.