npm package: @ivanlaomarketing/n8n-nodes-google-calendar-push
Description: Real-time Google Calendar Push Trigger for n8n — no polling, multi-calendar, instant webhook. By Ivan Lao · laoivan.com
Author: Ivan Lao
Latest version: 0.2.21

# n8n-nodes-google-calendar-push

[![npm version](https://img.shields.io/npm/v/@ivanlaomarketing/n8n-nodes-google-calendar-push.svg)](https://www.npmjs.com/package/@ivanlaomarketing/n8n-nodes-google-calendar-push)
[![npm downloads](https://img.shields.io/npm/dm/@ivanlaomarketing/n8n-nodes-google-calendar-push.svg)](https://www.npmjs.com/package/@ivanlaomarketing/n8n-nodes-google-calendar-push)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![n8n community node](https://img.shields.io/badge/n8n-community%20node-orange)](https://docs.n8n.io/integrations/community-nodes/)

A community node for [n8n](https://n8n.io) that triggers workflows in **real time** via **Google Calendar Push Notifications** (webhook-based), without polling.

> Built by [Ivan Lao](https://laoivan.com) — Marketing Automation & AI Specialist.

---

## Features

- ⚡ **Real-time triggers** — no polling, instant delivery via Google Calendar Push API
- 📅 **Multi-calendar support** — monitor multiple calendars simultaneously in a single node
- 🔁 **Auto-renewal** — channels are automatically renewed before expiration (30-day lifecycle)
- 🔍 **Trigger type detection** — distinguishes `CREATED`, `UPDATED`, and `DELETED` events
- 🧠 **Deterministic channel IDs** — prevents duplicate channels on re-activation
- 🔒 **OAuth2 authentication** — uses standard n8n Google OAuth2 credentials

---

## Installation

### From n8n UI (recommended)

1. Go to **Settings → Community Nodes**
2. Click **Install**
3. Enter: `@ivanlaomarketing/n8n-nodes-google-calendar-push`
4. Confirm and restart n8n if prompted

### Via CLI

```bash
npm install @ivanlaomarketing/n8n-nodes-google-calendar-push
```

---

## Prerequisites

- n8n instance **publicly accessible** (the webhook URL must be reachable by Google)
- A **Google Cloud project** with the Calendar API enabled
- An **OAuth2 credential** configured in n8n for Google Calendar

### Google OAuth2 Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create or select a project
3. Enable **Google Calendar API**
4. Create **OAuth 2.0 credentials** (Web application)
5. Add your n8n instance URL as an authorized redirect URI:
   `https://your-n8n-instance/rest/oauth2-credential/callback`
6. In n8n, create a new **Google OAuth2 API** credential and paste the Client ID and Secret

---

## Configuration

Add the **Google Calendar Push Trigger** node to your workflow and configure:

| Field | Description |
|-------|-------------|
| **Credential** | Google OAuth2 credential with Calendar access |
| **Calendar IDs** | One or more calendar IDs to monitor (e.g. `me` for primary, or a full calendar email) |
| **Max Results** | Maximum number of events to fetch per notification (default: 10) |

### Finding your Calendar ID

1. Open [Google Calendar](https://calendar.google.com)
2. Click the three dots next to a calendar → **Settings and sharing**
3. Scroll to **Integrate calendar** → copy the **Calendar ID**

---

## How It Works

1. On **workflow activation**, the node registers a push notification channel via the [Google Calendar Events: watch API](https://developers.google.com/calendar/api/v3/reference/events/watch) for each configured calendar.
2. Google sends a `POST` request to the n8n webhook URL whenever a calendar event changes.
3. The node fetches the changed events using the **syncToken** (incremental sync) and emits them.
4. On **workflow deactivation**, all registered channels are stopped via the [Channels: stop API](https://developers.google.com/calendar/api/v3/reference/channels/stop).
5. Channels are valid for **30 days** and are renewed automatically.

---

## Output Format

Each trigger execution emits one item per event:

```json
{
  "triggerType": "CREATED",
  "event": {
    "id": "abc123",
    "title": "Team Meeting",
    "description": "Weekly sync",
    "location": "Conference Room",
    "status": "confirmed",
    "start": {
      "dateTime": "2026-03-05T10:00:00+01:00",
      "timeZone": "Europe/Rome"
    },
    "end": {
      "dateTime": "2026-03-05T11:00:00+01:00",
      "timeZone": "Europe/Rome"
    },
    "created": "2026-03-01T08:00:00.000Z",
    "updated": "2026-03-01T08:00:01.000Z",
    "attendees": [],
    "organizer": {
      "email": "you@example.com",
      "self": true
    },
    "recurrence": [],
    "recurringEventId": null,
    "originalStartTime": null,
    "htmlLink": "https://www.google.com/calendar/event?eid=...",
    "conferenceData": null
  },
  "calendarId": "you@example.com",
  "calendarName": "My Calendar",
  "_sync": {
    "channelId": "wfId_calendarId",
    "channelExpiresAt": "2026-04-01T08:00:00.000Z",
    "processedAt": "2026-03-01T08:00:02.000Z"
  }
}
```

### Trigger Types

| Value | Description |
|-------|-------------|
| `CREATED` | A new event was added to the calendar |
| `UPDATED` | An existing event was modified |
| `DELETED` | An event was cancelled or removed |

---

## Troubleshooting

### "Bad request — please check your parameters" on activation
The webhook URL must be publicly reachable by Google. Verify that `https://your-n8n-instance/webhook/.../gcal-push` is accessible from the internet.

### "There is already an entry with this name" on activation
A stale webhook entry exists in n8n. Fix without restarting:
1. Delete the trigger node from the workflow
2. Save
3. Re-add the node with the same configuration
4. Save and activate

### Duplicate events arriving
This occurs when Google sends multiple push notifications for the same change (documented behavior). The node includes built-in deduplication based on `eventId + updated` timestamp with a 5-minute TTL window.

### Unknown channel warnings in logs
After reconfiguring the node, old channels may send pings for up to 30 days. These are automatically ignored and will stop after expiration — no action needed.

### Events not arriving
- Confirm the n8n webhook URL is publicly reachable
- Check that the Google Calendar API is enabled in your Google Cloud project
- Verify the OAuth2 token has the `https://www.googleapis.com/auth/calendar.readonly` scope
- Check n8n logs for `[GCalPush]` entries

---

## Compatibility

| n8n version | Status |
|-------------|--------|
| 1.x | ✅ Supported |
| 0.x | ⚠️ Not tested |

---

## Contributing

Pull requests and issues are welcome on [GitHub](https://github.com/ivanlaomarketing/n8n-nodes-google-calendar-push).

---

## Author

**Ivan Lao** — Marketing Automation & AI Specialist
🌐 [laoivan.com](https://laoivan.com)
💼 [LinkedIn](https://www.linkedin.com/in/ivanlaomarketing/)
▶️ [YouTube](https://www.youtube.com/@IvanLaoMarketing)

---

## License

[MIT](LICENSE)