Triggers And Webhooks

An agent should react when a specific user receives a new Gmail message. The operator enables the new-message trigger globally.

Enable the trigger scoped to the user's entity/connected account so events fire for that user's mailbox. A globally-enabled trigger either fails (no connection) or conflates users. Configure trigger params per entity.

Composio POSTs a trigger event to the operator's webhook endpoint. The handler parses the JSON and acts on it immediately.

Verify the webhook signature header against the shared secret before trusting or acting on the payload; reject unsigned/invalid requests. The exact signature scheme/header should be confirmed against current docs [REQUIRES-VERIFICATION]. Never act on an unverified webhook body.

The handler assumes every trigger payload has the same shape and reads a field that only exists for the Gmail trigger.

Branch on the trigger type and parse against that trigger's documented payload schema; different triggers (new email, new issue, new message) carry different fields. Validate presence before reading; degrade gracefully on unexpected shapes.