Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Trigger System Implementation |
| 2 | |
| 3 | This document explains the internal implementation of the trigger system in the Composio SDK. |
| 4 | |
| 5 | ## Architecture Overview |
| 6 | |
| 7 | The trigger system is built on top of Pusher for real-time communication. The implementation consists of two main components: |
| 8 | |
| 9 | 1. The Triggers class (`packages/core/src/models/Triggers.ts`) |
| 10 | 2. The PusherService class (`packages/core/src/services/pusher/Pusher.ts`) |
| 11 | |
| 12 | ## Real-time Communication |
| 13 | |
| 14 | ### Pusher Integration |
| 15 | |
| 16 | The SDK uses Pusher as the underlying real-time communication infrastructure. When a client subscribes to triggers, the following process occurs: |
| 17 | |
| 18 | 1. The SDK initializes a PusherService instance |
| 19 | 2. The service connects to Pusher using client credentials |
| 20 | 3. A channel subscription is established for the client's triggers |
| 21 | 4. Incoming messages are processed and filtered based on user-defined criteria |
| 22 | |
| 23 | ### Message Flow |
| 24 | |
| 25 | ```mermaid |
| 26 | sequenceDiagram |
| 27 | participant Client |
| 28 | participant SDK |
| 29 | participant Pusher |
| 30 | participant ComposioAPI |
| 31 | |
| 32 | Client->>SDK: subscribe(callback, filters) |
| 33 | SDK->>ComposioAPI: Authenticate Pusher connection |
| 34 | ComposioAPI-->>SDK: Connection credentials |
| 35 | SDK->>Pusher: Connect & Subscribe to channel |
| 36 | Pusher-->>SDK: Connection established |
| 37 | loop Real-time Events |
| 38 | Pusher->>SDK: Trigger event |
| 39 | SDK->>SDK: Apply filters |
| 40 | SDK->>Client: Filtered event callback |
| 41 | end |
| 42 | ``` |
| 43 | |
| 44 | ## API Endpoints |
| 45 | |
| 46 | The SDK interacts with the following Composio API endpoints for trigger management: |
| 47 | |
| 48 | ### Trigger Instance Management |
| 49 | |
| 50 | - `GET /api/v3/trigger_instances/active` - List active triggers |
| 51 | - `POST /api/v3/trigger_instances/{slug}` - Create/update trigger instance |
| 52 | - Includes `toolkit_versions` parameter to specify the toolkit version for the trigger instance (defaults to global configuration) |
| 53 | - `PATCH /api/v3/trigger_instances/manage/{id}` - Update trigger instance |
| 54 | - `DELETE /api/v3/trigger_instances/manage/{id}` - Delete trigger instance |
| 55 | |
| 56 | ### Trigger Types |
| 57 | |
| 58 | - `GET /api/v3/triggers/types` - List trigger types |
| 59 | - `GET /api/v3/triggers/types/{slug}` - Get trigger type details |
| 60 | - `GET /api/v3/triggers/types/enum` - Get trigger type enums |
| 61 | |
| 62 | ### Pusher Authentication |
| 63 | |
| 64 | - `POST /api/v3/internal/sdk/realtime/auth` - Authenticate Pusher connection |
| 65 | - `GET /api/v3/internal/sdk/realtime/credentials` - Necessary credentials to create pusher client |
| 66 | |
| 67 | ## Data Processing |
| 68 | |
| 69 | When a trigger event is received through Pusher, the SDK: |
| 70 | |
| 71 | 1. Parses the raw event data |
| 72 | 2. Validates it against the `IncomingTriggerPayloadSchema` |
| 73 | 3. Applies user-defined filters |
| 74 | 4. Delivers the processed event to the user's callback |
| 75 | |
| 76 | ### Filter Processing |
| 77 | |
| 78 | The SDK supports filtering triggers based on: |
| 79 | |
| 80 | - Toolkit names |
| 81 | - Trigger IDs |
| 82 | - Connected Account IDs |
| 83 | - Trigger slugs |
| 84 | - Trigger data |
| 85 | - User IDs |
| 86 | |
| 87 | Filters are applied in a compound manner - all specified filters must match for an event to be delivered. |
| 88 | |
| 89 | ## Error Handling |
| 90 | |
| 91 | The SDK implements robust error handling: |
| 92 | |
| 93 | - Schema validation for all incoming and outgoing data |
| 94 | - Connection error recovery |
| 95 | - Callback error isolation (errors in user callbacks don't affect the subscription) |
| 96 | - Automatic reconnection on connection loss |
| 97 | |
| 98 | ## Security Considerations |
| 99 | |
| 100 | - All Pusher communications are authenticated |
| 101 | - API credentials are never exposed to the client |
| 102 | - Each client only receives events they are authorized to see |
| 103 | - Connection credentials are short-lived and rotated regularly |