GWS Events Instant

Quickly subscribe to and monitor Google Workspace events with minimal configuration.

When to Use This Command

Run this command when you need to:

• Set up event watching on a Google Workspace resource like a calendar or drive folder instantly
• Monitor changes to specific files, calendars, or user directories in real time
• Debug event delivery by listing recent events and their payload contents

Consider alternatives when:

• You need complex event filtering and transformation which requires a dedicated event pipeline
• You are building a production integration that needs the full events management command

Quick Start

Configuration

Copy
name: gws-events-instant
type: command
category: google-workspace

Example Invocation

Copy
claude command:run gws-events-instant --watch "calendar:primary" --webhook "https://api.example.com/hooks/cal"

Example Output

Setting up event watch...
  Resource: calendar:primary
  Webhook: https://api.example.com/hooks/cal

Subscription created:
  Channel ID: ch_instant_7f2a
  Resource ID: res_cal_primary
  Expiration: 2026-04-14 (30 days)
  Status: ACTIVE

Waiting for events... (Ctrl+C to stop monitoring)
  [14:23:08] Event received: calendar.event.created
    Summary: "Team Standup"
    Start: 2026-03-16 09:00
  [14:25:41] Event received: calendar.event.updated
    Summary: "Sprint Review" (rescheduled)

Core Concepts

Instant Event Monitoring Overview

Aspect	Details
Resources	Calendar, Drive files/folders, Admin directory, Groups
Watch Mode	Subscribe to a resource and receive push notifications on change
Debug Mode	Tail incoming events in real time for debugging webhook handlers
One-Shot	Create quick subscriptions that auto-expire for temporary monitoring
Format	Events delivered as JSON payloads with resource ID and change type

Event Watch Workflow

Specify Resource
       |
       v
Create Watch Channel
       |
       v
Receive Sync Event
  (confirms channel is active)
       |
       v
Monitor Changes
  |           |
  v           v
Push to     Display in
Webhook     Terminal
  |           |
  v           v
Process     Debug
Events      Output

Configuration

Parameter	Type	Default	Description
watch	string	(required)	Resource to watch in service:id format
webhook	string	(required)	Webhook URL to receive push notifications
ttl	integer	30	Watch duration in days before auto-expiry
debug	boolean	false	Display events in terminal as they arrive
format	string	json	Event payload format: json or summary

Best Practices

1. Start with debug mode - Use the debug flag to see events in your terminal before relying on the webhook. This verifies the subscription is working and shows the exact payload format.

2. Use specific resource IDs - Watching calendar:primary is more efficient than watching all calendars. Narrow the scope to reduce noise and API quota consumption.

3. Handle the sync event - The first event after subscription creation is a sync notification, not an actual change. Your webhook handler should recognize and ignore this initial sync.

4. Set appropriate TTL values - For temporary debugging sessions, use short TTL values like 1 day. For ongoing monitoring, use the maximum duration and set up renewal.

Common Issues

1. No events received after subscription - The most common cause is a webhook URL that is not publicly accessible. Test your endpoint with curl before creating the subscription.

2. Events arrive with delay - Some resource types have inherent latency in event delivery. Calendar events are typically near-instant while Drive file changes may have up to a 60-second delay.

3. Watch quota exceeded - Google limits the number of active watch channels per resource. Stop unused watches with the stop command before creating new ones. Run a periodic audit of active watches to identify and remove abandoned subscriptions that consume quota without delivering useful events.

4. Sync event mistaken for real change - The first notification after creating a watch is always a sync event, not a real resource change. Your webhook handler must check the notification type and ignore sync events to avoid processing phantom changes in your application logic.