Gmail Webhooks

The Gmail plugin automatically handles incoming webhooks from Gmail via Google Pub/Sub. Configure Gmail Watch to send notifications to your Pub/Sub topic, and the plugin will automatically process events and update your database.

Setup

Gmail webhooks use Google Pub/Sub. Configure your webhook endpoint to handle Pub/Sub notifications:

import { processWebhook } from "corsair";
import { corsair } from "@/server/corsair";

export async function POST(request: Request) {
    const headers = Object.fromEntries(request.headers);
    const body = await request.json();
    
    const result = await processWebhook(corsair, headers, body);
    return result.response;
}

Set up a Pub/Sub push subscription pointing to your webhook endpoint:

https://your-domain.com/api/webhook

For multi-tenancy, include the tenant ID:

https://your-domain.com/api/webhook?tenantId=tenant-123

Available Webhooks

messageChanged

messageChanged

Event Type: Message Changed

Fires when a message is received, deleted, or has its labels modified. The handler automatically determines the change type from Gmail's history API and returns the appropriate event.

When it fires: A new email arrives, a message is deleted, or labels are added/removed from a message.

Possible event types in result.data.type:

• messageReceived — A new email was received
• messageDeleted — A message was permanently deleted
• messageLabelChanged — Labels were added or removed from a message

Example Usage:

gmail({
    webhookHooks: {
        messageChanged: {
            after: async (ctx, result) => {
                console.log(`Gmail event: ${result.data?.type}`);
                
                if (result.data?.type === 'messageReceived') {
                    await processNewEmail(result.data.message);
                }
                
                if (result.data?.type === 'messageDeleted') {
                    console.log('Message deleted');
                }
                
                if (result.data?.type === 'messageLabelChanged') {
                    console.log('Labels changed on message');
                }
            },
        },
    },
})

Configuring Gmail Watch

To receive webhook events, you need to set up Gmail Watch:

1. Go to Google Cloud Console
2. Create a Pub/Sub topic
3. Configure Gmail Watch API to send notifications to your Pub/Sub topic
4. Set up a Pub/Sub push subscription pointing to your webhook endpoint

Gmail webhooks use Pub/Sub, so no signing secret is needed. The webhook will receive Pub/Sub notifications with base64 encoded message data.

See the Gmail API documentation for more information.