Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 252 lines 10.1 KB
Raw
1 ---
2 title: "Triggers"
3 description: "Triggers (instance) class"
4 ---
5
6 ## Methods
7
8 ### set_webhook_subscription()
9
10 Create or update the project webhook subscription used for webhook delivery. If a subscription already exists, the first subscription is updated. Otherwise a new subscription is created. By default this subscribes to V3 trigger message events.
11
12 ```python
13 def set_webhook_subscription(*, webhook_url: str, enabled_events: Sequence[str] | None = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription
14 ```
15
16 **Parameters**
17
18 | Name | Type |
19 |------|------|
20 | `webhook_url` | `str` |
21 | `enabled_events?` | `Sequence[str] \| None` |
22 | `version?` | `Union[WebhookVersion, str]` |
23
24 **Returns**
25
26 `WebhookSubscription`
27
28 **Example**
29
30 ```python
31 composio.triggers.set_webhook_subscription(
32 webhook_url=f"{APP_URL}/webhooks/composio",
33 )
34 ```
35
36 ---
37
38 ### get_type()
39
40 Get a trigger type by its slug Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version
41
42 ```python
43 def get_type(slug: str) -> TriggersTypeRetrieveResponse
44 ```
45
46 **Parameters**
47
48 | Name | Type | Description |
49 |------|------|-------------|
50 | `slug` | `str` | The slug of the trigger type |
51
52 **Returns**
53
54 `TriggersTypeRetrieveResponse` — The trigger type
55
56 ---
57
58 ### list_active()
59
60 List all active triggers
61
62 ```python
63 def list_active(trigger_ids: list[str] | None = ..., trigger_names: list[str] | None = ..., auth_config_ids: list[str] | None = ..., connected_account_ids: list[str] | None = ..., show_disabled: bool | None = ..., limit: int | None = ..., cursor: str | None = ...)
64 ```
65
66 **Parameters**
67
68 | Name | Type | Description |
69 |------|------|-------------|
70 | `trigger_ids?` | `list[str] \| None` | List of trigger IDs to filter by |
71 | `trigger_names?` | `list[str] \| None` | List of trigger names to filter by |
72 | `auth_config_ids?` | `list[str] \| None` | List of auth config IDs to filter by |
73 | `connected_account_ids?` | `list[str] \| None` | List of connected account IDs to filter by |
74 | `show_disabled?` | `bool \| None` | Whether to show disabled triggers |
75 | `limit?` | `int \| None` | Limit the number of triggers to return |
76 | `cursor?` | `str \| None` | Cursor for pagination. Use the nextCursor from the response to get the next page. |
77
78 ---
79
80 ### list()
81
82 List all the trigger types.
83
84 ```python
85 def list(*, cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str] | None = ...)
86 ```
87
88 **Parameters**
89
90 | Name | Type | Description |
91 |------|------|-------------|
92 | `cursor?` | `str \| None` | The cursor for pagination |
93 | `limit?` | `int \| None` | The maximum number of trigger types to return |
94 | `toolkit_slugs?` | `list[str] \| None` | Filter by toolkit slugs |
95
96 ---
97
98 ### create()
99
100 Create a trigger instance
101
102 ```python
103 def create(slug: str, *, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any] | None = ..., type: Literal['webhook', 'poll'] | None = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes...
104 ```
105
106 **Parameters**
107
108 | Name | Type | Description |
109 |------|------|-------------|
110 | `slug` | `str` | The slug of the trigger |
111 | `user_id?` | `str \| None` | The ID of the user that owns the connected account. When `connected_account_id` is omitted, the backend resolves the first active connection for this user and the trigger's toolkit. |
112 | `connected_account_id?` | `str \| None` | The ID of the connected account to pin |
113 | `trigger_config?` | `Dict[str, Any] \| None` | The configuration of the trigger |
114 | `type?` | `Literal['webhook', 'poll'] \| None` | `webhook` or `poll`, for a trigger that supports both. Omit it to let Composio choose. |
115 | `polling_interval?` | `int \| None` | Minutes between polls, for an instance that polls. Wins over `trigger_config["interval"]`. |
116
117 **Returns**
118
119 `trigger_instance_upsert_response.TriggerInstanceUpsertRes...` — The trigger instance, with the `type` it uses, the `fallback_reason` when it polls after a webhook was unavailable, and its `polling_interval`
120
121 ---
122
123 ### subscribe()
124
125 Subscribe to a trigger and receive trigger events.
126
127 ```python
128 def subscribe(timeout: float = ..., on_subscription_error: SubscriptionErrorCallback | None = ...) -> TriggerSubscription
129 ```
130
131 **Parameters**
132
133 | Name | Type | Description |
134 |------|------|-------------|
135 | `timeout?` | `float` | The timeout to wait for the subscription to be established. |
136 | `on_subscription_error?` | `SubscriptionErrorCallback \| None` | Optional callback invoked when the channel subscription fails: with the raw Pusher payload for asynchronous `pusher:subscription_error` events (for example a later permission rejection), or with `{"error": ...}` for failures raised while establishing the subscription (for example an auth rejection — pysher performs channel auth synchronously). Establish-time failures also make `subscribe()` raise the underlying error promptly instead of waiting out the timeout. Exceptions raised inside the callback are contained and logged, never rethrown. |
137
138 **Returns**
139
140 `TriggerSubscription` — The trigger subscription handler.
141
142 ---
143
144 ### verify_webhook()
145
146 Verify an incoming webhook payload and signature. This method validates that the webhook request is authentic by: 1. Validating the webhook timestamp is within the tolerance window 2. Verifying the HMAC-SHA256 signature using the correct algorithm 3. Parsing the payload and detecting the webhook version (V1, V2, or V3)
147
148 ```python
149 def verify_webhook(*, id: str, payload: str, secret: str, signature: str, timestamp: str, tolerance: int = ...) -> VerifyWebhookResult
150 ```
151
152 **Parameters**
153
154 | Name | Type | Description |
155 |------|------|-------------|
156 | `id` | `str` | The webhook message ID from the 'webhook-id' header (format: 'msg_xxx') |
157 | `payload` | `str` | The raw webhook payload as a string (request body) |
158 | `secret` | `str` | The webhook secret used to sign the payload (from Composio dashboard) |
159 | `signature` | `str` | The signature from the 'webhook-signature' header (format: 'v1,base64EncodedSignature') |
160 | `timestamp` | `str` | The webhook timestamp from the 'webhook-timestamp' header (Unix seconds) |
161 | `tolerance?` | `int` | Maximum allowed age of the webhook in seconds (default: 300 = 5 minutes). Set to 0 to disable timestamp validation. |
162
163 **Returns**
164
165 `VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload
166
167 **Raises**
168
169 - `WebhookSignatureVerificationError` — If the signature verification fails
170 - `WebhookPayloadError` — If the payload cannot be parsed or is invalid
171
172 **Example**
173
174 ```python
175 # In a Flask webhook handler
176 @app.route('/webhook', methods=['POST'])
177 def webhook():
178 try:
179 result = composio.triggers.verify_webhook(
180 id=request.headers.get('webhook-id', ''),
181 payload=request.get_data(as_text=True),
182 signature=request.headers.get('webhook-signature', ''),
183 timestamp=request.headers.get('webhook-timestamp', ''),
184 secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
185 )
186
187 # Process the verified payload
188 print(f"Version: {result['version']}")
189 print(f"Received trigger: {result['payload']['trigger_slug']}")
190 return 'OK', 200
191 except WebhookSignatureVerificationError:
192 return 'Unauthorized', 401
193 ```
194
195 ---
196
197 ### parse()
198
199 Parse an incoming webhook request into a typed, normalized trigger payload. Pass a framework request object, or pass `body=` and `headers=` explicitly. When `verify_secret` is provided, the SDK verifies the webhook signature before returning the normalized trigger payload. When it is omitted, the SDK parses the body without verifying the signature. `request` may be any object exposing the request body and headers, such as a Flask, Django, or FastAPI request. The body is read from `.body` (or `.data` / `.get_data()`), and the headers are read from `.headers`. Because this SDK is synchronous, async frameworks must pass an already-read raw body, for example via `body=await request.body()`.
200
201 ```python
202 def parse(request: Any = ..., *, body: Union[str, bytes, Mapping[str, Any], None] = ..., headers: Union[Mapping[str, Any], None] = ..., verify_secret: Union[str, None, Omit] = ..., tolerance: int = ...) -> VerifyWebhookResult
203 ```
204
205 **Parameters**
206
207 | Name | Type | Description |
208 |------|------|-------------|
209 | `request?` | `Any` | The incoming webhook request object (Flask/Django/FastAPI) |
210 | `body?` | `Union[str, bytes, Mapping[str, Any], None]` | The raw request body (str/bytes/parsed mapping); overrides `request` |
211 | `headers?` | `Union[Mapping[str, Any], None]` | The request headers as a mapping; overrides `request` |
212 | `verify_secret?` | `Union[str, None, Omit]` | Webhook secret; when set, the signature is verified. Omit it entirely to parse without verification. Passing a present-but-empty value (e.g. an unset `COMPOSIO_WEBHOOK_SECRET`) raises rather than silently skipping verification. |
213 | `tolerance?` | `int` | Max webhook age in seconds (only used when verifying) |
214
215 **Returns**
216
217 `VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload
218
219 **Raises**
220
221 - `ValidationError` — If `verify_secret` is empty, or is set but signature headers are missing
222 - `WebhookSignatureVerificationError` — If signature verification fails
223 - `WebhookPayloadError` — If the payload cannot be parsed
224
225 **Example**
226
227 ```python
228 # Flask: verify the signature
229 @app.route('/webhooks/composio', methods=['POST'])
230 def webhook():
231 try:
232 result = composio.triggers.parse(
233 request,
234 verify_secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
235 )
236 print(f"Trigger: {result['payload']['trigger_slug']}")
237 print(f"Event data: {result['payload']['payload']}")
238 return 'OK', 200
239 except exceptions.WebhookSignatureVerificationError:
240 return 'Unauthorized', 401
241
242 # FastAPI: parse without verifying after reading the async body
243 @app.post('/webhooks/composio')
244 async def webhook(request: Request):
245 raw = await request.body()
246 result = composio.triggers.parse(body=raw, headers=request.headers)
247 return {'trigger': result['payload']['trigger_slug']}
248 ```
249
250 ---
251
252 [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py#L1160)