Webhooks

Webhooks allow you to receive real-time notifications when events occur in Google Workspace services.

Overview

Gspace provides webhook support for:

  • Calendar event changes
  • Gmail message events
  • Drive file changes
  • Sheets updates

Setting Up Webhooks

1. Create a Webhook Handler

python
from gspace.webhooks import WebhookHandler

handler = WebhookHandler(secret="your_secret_key")

2. Register Event Handlers

python
@handler.on_event("calendar.event.created")
def handle_calendar_event(event):
    print(f"New calendar event: {event.data}")

@handler.on_event("gmail.message.received")
def handle_gmail_message(event):
    print(f"New email received: {event.data}")

3. Set Up Your Server Endpoint

python
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data()
    
    # Verify and process webhook
    event = handler.verify_and_process(payload, signature)
    handler.dispatch(event)
    
    return {'status': 'ok'}, 200

Supported Events

Calendar Events

  • calendar.event.created - New event created
  • calendar.event.updated - Event updated
  • calendar.event.deleted - Event deleted

Gmail Events

  • gmail.message.received - New message received
  • gmail.message.sent - Message sent
  • gmail.label.added - Label added to message

Drive Events

  • drive.file.created - New file created
  • drive.file.updated - File updated
  • drive.file.deleted - File deleted
  • drive.file.shared - File sharing changed

Sheets Events

  • sheets.spreadsheet.updated - Spreadsheet updated
  • sheets.range.updated - Range of cells updated

Verifying Webhooks

Always verify webhook signatures to ensure requests are authentic:

python
def verify_webhook(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

Best Practices

  1. Verify signatures - Always verify webhook signatures
  2. Handle duplicates - Webhooks may be delivered multiple times
  3. Idempotency - Make handlers idempotent
  4. Error handling - Handle errors gracefully and log them
  5. Rate limiting - Implement rate limiting for webhook endpoints