Skip to main content
Build a local Python or TypeScript service that summarizes new Gmail messages when Composio delivers a webhook. Both handlers verify the signature, check the event’s user and account, and run an agent with access to that account’s email-reading tool. This combines the repository’s Python trigger example with the verification pattern in the TypeScript webhook server. It stores completed summaries in SQLite so redelivery of the same event doesn’t run the agent again.

Install and connect Gmail

Use Python 3.12 or Node.js 24 and a disposable Composio project. The setup script registers a project-wide webhook URL; if a subscription already exists, it updates that subscription.
Get a Composio project key and an OpenAI key. Your local server will listen on port 8000. Use one of the local webhook forwarding options to get a public HTTPS URL that forwards to that port. Keep the forwarding process running and set the full endpoint URL:
Save the setup script for your language and run it once. The API option performs the same authorization, subscription upsert, and trigger creation. Open the printed Connect Link to authorize the Gmail account you want to monitor.
setup.py
Copy the three values into the shell where you will start the handler. Keep the signing secret private:
Deleting the setup session leaves the connected Gmail account and trigger in place. If your Gmail trigger requires additional configuration, inspect its current schema with composio.triggers.get_type("GMAIL_NEW_GMAIL_MESSAGE") before creating it, as described in creating triggers.

Verify the event and run the agent

Save the handler as server.py or server.ts. Both versions process one request at a time and acknowledge the webhook after storing the summary. Keep the database file between restarts to preserve completed event IDs. Signature verification and the OpenAI agent loop run in your application, not through a Composio REST endpoint.
server.py
The handler passes the unchanged body to signature verification. It then checks the trigger, user, and connected account before creating a session. A valid signature authenticates delivery from your project; those additional checks choose which account this particular agent may use. The SQLite key is the V3 event envelope’s id. The normalized event["id"] (Python) or event.id (TypeScript) identifies the trigger instance, which is shared by many emails and must not be used to deduplicate messages.

Test delivery

First, send an unsigned request. It should return 401 without running the agent:
Then send a new email to the connected Gmail account. Keep both the server and forwarding process running. Allow time for the Gmail trigger to detect the message. A successful delivery prints Saved summary for event .... Inspect the stored summary from a second terminal:
The summary should describe the email you just sent. If no event arrives, check that the trigger is active, the public URL still forwards to port 8000, and the server uses the secret from the same project subscription. See receiving events.

Stop the demo and prepare for production

Delete the trigger when you finish testing:
Stop the server and forwarding process. The local database contains email summaries; keep or remove it according to your application’s data policy. For production, verify and store each event in a durable queue before returning 2xx, then run the agent in a worker. This local server waits for the model and can exceed the webhook delivery timeout. Its SQLite deduplication prevents repeat runs after a completed write, but a crash between model execution and that write can run the model again. For multiple users, resolve the signed event’s account ID through your stored account-to-user mapping. Keep the same session account pinning and tool restriction. See consumer agent architecture for the ownership model.