Smart GWS Events Renew

Renew and manage Google Workspace event subscriptions for push notifications and real-time updates.

When to Use This Command

Run this command when you need to:

• Renew expiring webhook subscriptions for Calendar, Drive, or other Workspace event channels
• Monitor and manage active event subscriptions across your Google Workspace integration
• Set up new push notification channels for real-time event delivery to your webhook endpoints

Consider alternatives when:

• You need one-time data retrieval rather than ongoing event streaming, use polling APIs instead
• You are setting up event subscriptions for the first time and need full channel configuration

Quick Start

Configuration

Copy
name: smart-gws-events-renew
type: command
category: google-workspace

Example Invocation

Copy
claude command:run smart-gws-events-renew --service calendar --channel-id "ch_abc123"

Example Output

Renewing event subscription...
  Service: Google Calendar
  Channel ID: ch_abc123
  Webhook: https://api.example.com/webhooks/calendar

Current subscription:
  Created: 2026-03-01
  Expires: 2026-03-15 (TODAY)
  Events delivered: 847

Renewal result:
  New expiration: 2026-04-14
  Token: tkn_renewed_9x2f
  Status: ACTIVE

Subscription renewed for 30 days.

Core Concepts

Event Subscription Overview

Aspect	Details
Services	Calendar, Drive, Admin, Gmail (via pub/sub), Groups event streams
Channels	Push notification channels delivering events to your webhook URL
Expiration	Subscriptions expire after a set period and must be renewed proactively
Token	Verification token included in push notifications for request authenticity
Reliability	At-least-once delivery with deduplication by resource ID and timestamp

Subscription Lifecycle

Create Subscription
        |
        v
Active (receiving events)
        |
        v
Approaching Expiration
  (renewal window)
        |
        v
Renew Subscription
        |
        v
Active (extended)
        |
  (if not renewed)
        v
Expired (events stop)

Configuration

Parameter	Type	Default	Description
service	string	(required)	Target service: calendar, drive, admin, gmail
channel-id	string	(none)	Existing channel ID to renew
webhook	string	(none)	Webhook URL for new subscriptions
ttl	integer	30	Subscription duration in days
auto-renew	boolean	false	Set up automatic renewal before expiration

Best Practices

1. Renew before expiration - Set up monitoring to renew subscriptions at least 24 hours before they expire. Missing the renewal window means losing events until a new subscription is created.

2. Use auto-renew for critical channels - For subscriptions that power production features, enable auto-renew to prevent service disruptions from forgotten manual renewals.

3. Validate webhook endpoints - Ensure your webhook URL is accessible and responds with 200 status before renewing. A subscription pointing to a broken endpoint wastes quota and masks failures.

4. Track subscriptions centrally - Maintain a registry of all active subscriptions with their channel IDs, services, and expiration dates so nothing falls through the cracks.

Common Issues

1. Renewal fails with channel not found - The channel may have already expired. Create a new subscription instead of renewing since expired channels cannot be revived.

2. Duplicate events after renewal - Brief overlap during renewal can cause duplicate deliveries. Implement idempotency in your webhook handler using the resource ID as a deduplication key.

3. Webhook receives no events after renewal - Verify the webhook endpoint is publicly accessible and returns HTTP 200. Google stops pushing to endpoints that consistently fail with non-200 responses. Test the endpoint independently with a curl request before troubleshooting the subscription configuration.

4. Subscription TTL shorter than expected - Google may impose a maximum TTL that is shorter than your requested duration depending on the service and resource type. Check the actual expiration in the renewal response rather than assuming the requested TTL was honored.

5. Channel token mismatch after renewal - The renewal process may issue a new verification token. Update your webhook handler to accept the new token value or configure it to validate against a list of known tokens to avoid rejecting legitimate push notifications.