/webhook_subscriptions/event_types endpoint, then create a subscription scoped to the ones you care about.
Each subscription is addressed by its id. You can update its URL and filters with PATCH, delete it, and rotate its signing secret with /webhook_subscriptions/{id}/rotate_secret if the secret leaks.
Every webhook request Composio sends includes webhook-id, webhook-timestamp, and webhook-signature headers. Store the secret as COMPOSIO_WEBHOOK_SECRET and verify each payload before trusting it. See Verifying signatures for the SDK and manual verification flows.
Event types
A subscription’senabled_events controls which events get delivered to its URL. Two broad families exist:
- Trigger events like
composio.trigger.message— payloads emitted by triggers you’ve enabled (new email, new issue, etc.). - Lifecycle events like
composio.connected_account.expired— emitted when a connected account changes state.
/webhook_subscriptions/event_types endpoint, then scope a subscription to the events you handle.
Detecting connection expiry
Composio automatically refreshes OAuth tokens before they expire. But when a refresh token is revoked or expires, the connection enters anEXPIRED state and the user must re-authenticate.
Subscribe to the composio.connected_account.expired event to detect this proactively, instead of waiting for a tool execution to fail.
whs_123 with the ID from List webhook subscriptions. Include any other events you want to keep in enabled_events.
- Python
- TypeScript
- API
type to handle expiry alongside trigger events:
- Python
- TypeScript