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
py 1,906 lines 75.9 KB
Raw
1 from __future__ import annotations
2
3 import base64
4 import functools
5 import hashlib
6 import hmac
7 import json
8 import logging
9 import re
10 import threading
11 import time
12 import traceback
13 import typing as t
14 import uuid
15 from concurrent.futures import ThreadPoolExecutor
16
17 import requests
18 import typing_extensions as te
19 from composio_client import APIStatusError, Omit, omit
20 from composio_client.types import TriggersTypeRetrieveResponse
21 from pysher import Pusher
22 from pysher.channel import Channel as PusherChannel
23 from pysher.connection import Connection as PusherConnection
24
25 from composio import exceptions
26 from composio.client import HttpClient
27 from composio.client.types import trigger_instance_upsert_response
28 from composio.core.models.base import Resource, credential_headers
29 from composio.core.models.internal import Internal
30 from composio.core.models.webhooks import (
31 DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS,
32 WebhookSubscription,
33 WebhookSubscriptions,
34 WebhookVersion,
35 )
36 from composio.core.types import ToolkitVersionParam
37 from composio.exceptions import ComposioSDKTimeoutError
38 from composio.utils.logging import WithLogger
39 from composio.utils.pydantic import none_to_omit
40
41 PUSHER_AUTH_URL = "{base_url}/api/v3/internal/sdk/realtime/auth?source=python"
42
43 # `(connect, read)` seconds for the channel-auth POST pysher makes on the
44 # websocket thread. pysher itself sends it with no timeout, so an auth endpoint
45 # that accepts the connection and never answers would hang every (re)subscribe
46 # for the life of the process.
47 PUSHER_AUTH_TIMEOUT: t.Tuple[float, float] = (5.0, 15.0)
48
49 # Pusher cluster names are short lowercase labels such as ``mt1`` or
50 # ``ap-southeast-1``. pysher formats the value straight into the websocket
51 # host (``ws-{cluster}.pusher.com``), and it arrives in an API response, which
52 # `python/AGENTS.md` treats as untrusted: anything outside this shape could
53 # steer the socket to a host of the response author's choosing.
54 _PUSHER_CLUSTER_PATTERN = re.compile(r"^[a-z0-9-]+$")
55 _PUSHER_CLUSTER_MAX_LENGTH = 64
56
57 _PYSHER_LOGGER_NAME = "composio.core.models.triggers.pysher"
58
59 """
60 export type _TriggerData = {
61 appName: string;
62 clientId: number;
63 payload: Record<string, unknown>;
64 originalPayload: Record<string, unknown>;
65 metadata: {
66 id: string;
67 nanoId: string;
68 triggerName: string;
69 triggerData: string;
70 triggerConfig: Record<string, unknown>;
71 connection: {
72 id: string;
73 connectedAccountNanoId: string;
74 integrationId: string;
75 authConfigNanoId: string;
76 clientUniqueUserId: string;
77 status: string;
78 };
79 };
80 };
81 """
82
83
84 class _ConnectionData(te.TypedDict):
85 id: str
86 status: t.Literal["ACTIVE", "INACTIVE"]
87 integrationId: str
88 authConfigNanoId: str
89 clientUniqueUserId: str
90 connectedAccountNanoId: str
91
92
93 class _TriggerMetadata(te.TypedDict):
94 id: str
95 nanoId: str
96 triggerName: str
97 triggerData: str
98 triggerConfig: t.Dict
99 connection: _ConnectionData
100
101
102 class _TriggerData(te.TypedDict):
103 clientId: str
104 appName: str
105 payload: t.Dict
106 metadata: _TriggerMetadata
107 originalPayload: t.Dict
108
109
110 class WebhookPayloadV1(te.TypedDict):
111 """V1 webhook payload structure."""
112
113 trigger_name: str
114 connection_id: str
115 trigger_id: str
116 payload: t.Dict[str, t.Any]
117 log_id: str
118
119
120 class WebhookPayloadV2(te.TypedDict):
121 """V2 webhook payload structure."""
122
123 type: str
124 timestamp: str
125 log_id: str
126 data: t.Dict[str, t.Any]
127
128
129 class WebhookPayloadV3(te.TypedDict):
130 """V3 webhook payload structure - generic envelope for all composio.* events."""
131
132 id: str
133 timestamp: str
134 type: str # Any composio.* event type (e.g., 'composio.trigger.message', 'composio.connected_account.expired')
135 metadata: t.Dict[
136 str, t.Any
137 ] # Shape varies by event type (trigger vs connection events)
138 data: t.Dict[str, t.Any]
139
140
141 class WebhookTriggerPayloadV3Metadata(te.TypedDict):
142 """V3 trigger-specific webhook payload metadata."""
143
144 log_id: str
145 trigger_slug: str
146 trigger_id: str
147 connected_account_id: str
148 auth_config_id: str
149 user_id: str
150
151
152 class WebhookTriggerPayloadV3(te.TypedDict):
153 """V3 trigger-specific webhook payload structure."""
154
155 id: str
156 timestamp: str
157 type: str
158 metadata: WebhookTriggerPayloadV3Metadata
159 data: t.Dict[str, t.Any]
160
161
162 WebhookPayload = t.Union[WebhookPayloadV1, WebhookPayloadV2, WebhookPayloadV3]
163
164
165 class TriggerConnectedAccountSchema(t.TypedDict):
166 id: str
167 uuid: str
168 user_id: str
169 auth_config_id: str
170 auth_config_uuid: str
171 status: t.Literal["ACTIVE", "INACTIVE"]
172
173
174 class TriggerMetadataSchema(t.TypedDict):
175 id: str
176 toolkit_slug: str
177 trigger_slug: str
178 trigger_data: t.Optional[str]
179 trigger_config: t.Dict[str, t.Any]
180 connected_account: TriggerConnectedAccountSchema
181
182
183 class TriggerEvent(t.TypedDict):
184 id: str # The ID of the trigger
185 uuid: str # UUID of the trigger
186 user_id: str # The ID of the user that triggered the event
187
188 trigger_slug: str # The slug of the trigger that triggered the event
189 toolkit_slug: str # The slug of the toolkit that triggered the event
190
191 payload: t.Optional[t.Dict[str, t.Any]] # The payload of the trigger
192 metadata: TriggerMetadataSchema
193 original_payload: t.Optional[
194 t.Dict[str, t.Any]
195 ] # The original payload of the trigger
196
197
198 class VerifyWebhookResult(t.TypedDict):
199 """Result of webhook verification."""
200
201 version: WebhookVersion # The webhook version (V1, V2, or V3)
202 payload: TriggerEvent # The parsed and normalized webhook payload
203 raw_payload: WebhookPayload # The original parsed payload
204
205
206 # Re-exported for backwards compatibility; the definitions live in
207 # :mod:`composio.core.models.webhooks`.
208 __all__ = [
209 "DEFAULT_WEBHOOK_SUBSCRIPTION_EVENTS",
210 "Triggers",
211 "WebhookSubscription",
212 "WebhookVersion",
213 ]
214
215
216 _ = {
217 "appName": "github",
218 "payload": {
219 "author": "angrybayblade",
220 "id": "a2334682759c4324e911d8f52f8fb6bdf1338d94",
221 "message": "temp",
222 "timestamp": "2025-06-19T11:28:01+05:30",
223 "url": "https://github.com/angrybayblade/ph7/commit/a2334682759c4324e911d8f52f8fb6bdf1338d94",
224 },
225 "originalPayload": {
226 "ref": "refs/heads/temp",
227 "before": "e5eb72bc9f973b6cc82e0de9708660c5341befe5",
228 "after": "a2334682759c4324e911d8f52f8fb6bdf1338d94",
229 "repository": {
230 "id": 752122629,
231 "node_id": "R_kgDOLNR7BQ",
232 "name": "ph7",
233 "full_name": "angrybayblade/ph7",
234 "private": False,
235 "owner": {
236 "name": "angrybayblade",
237 "email": "35092918+angrybayblade@users.noreply.github.com",
238 "login": "angrybayblade",
239 "id": 35092918,
240 "node_id": "MDQ6VXNlcjM1MDkyOTE4",
241 "avatar_url": "https://avatars.githubusercontent.com/u/35092918?v=4",
242 "gravatar_id": "",
243 "url": "https://api.github.com/users/angrybayblade",
244 "html_url": "https://github.com/angrybayblade",
245 "followers_url": "https://api.github.com/users/angrybayblade/followers",
246 "following_url": "https://api.github.com/users/angrybayblade/following{/other_user}",
247 "gists_url": "https://api.github.com/users/angrybayblade/gists{/gist_id}",
248 "starred_url": "https://api.github.com/users/angrybayblade/starred{/owner}{/repo}",
249 "subscriptions_url": "https://api.github.com/users/angrybayblade/subscriptions",
250 "organizations_url": "https://api.github.com/users/angrybayblade/orgs",
251 "repos_url": "https://api.github.com/users/angrybayblade/repos",
252 "events_url": "https://api.github.com/users/angrybayblade/events{/privacy}",
253 "received_events_url": "https://api.github.com/users/angrybayblade/received_events",
254 "type": "User",
255 "user_view_type": "public",
256 "site_admin": False,
257 },
258 "html_url": "https://github.com/angrybayblade/ph7",
259 "description": "💧 Python native HTML rendering",
260 "fork": False,
261 "url": "https://api.github.com/repos/angrybayblade/ph7",
262 "forks_url": "https://api.github.com/repos/angrybayblade/ph7/forks",
263 "keys_url": "https://api.github.com/repos/angrybayblade/ph7/keys{/key_id}",
264 "collaborators_url": "https://api.github.com/repos/angrybayblade/ph7/collaborators{/collaborator}",
265 "teams_url": "https://api.github.com/repos/angrybayblade/ph7/teams",
266 "hooks_url": "https://api.github.com/repos/angrybayblade/ph7/hooks",
267 "issue_events_url": "https://api.github.com/repos/angrybayblade/ph7/issues/events{/number}",
268 "events_url": "https://api.github.com/repos/angrybayblade/ph7/events",
269 "assignees_url": "https://api.github.com/repos/angrybayblade/ph7/assignees{/user}",
270 "branches_url": "https://api.github.com/repos/angrybayblade/ph7/branches{/branch}",
271 "tags_url": "https://api.github.com/repos/angrybayblade/ph7/tags",
272 "blobs_url": "https://api.github.com/repos/angrybayblade/ph7/git/blobs{/sha}",
273 "git_tags_url": "https://api.github.com/repos/angrybayblade/ph7/git/tags{/sha}",
274 "git_refs_url": "https://api.github.com/repos/angrybayblade/ph7/git/refs{/sha}",
275 "trees_url": "https://api.github.com/repos/angrybayblade/ph7/git/trees{/sha}",
276 "statuses_url": "https://api.github.com/repos/angrybayblade/ph7/statuses/{sha}",
277 "languages_url": "https://api.github.com/repos/angrybayblade/ph7/languages",
278 "stargazers_url": "https://api.github.com/repos/angrybayblade/ph7/stargazers",
279 "contributors_url": "https://api.github.com/repos/angrybayblade/ph7/contributors",
280 "subscribers_url": "https://api.github.com/repos/angrybayblade/ph7/subscribers",
281 "subscription_url": "https://api.github.com/repos/angrybayblade/ph7/subscription",
282 "commits_url": "https://api.github.com/repos/angrybayblade/ph7/commits{/sha}",
283 "git_commits_url": "https://api.github.com/repos/angrybayblade/ph7/git/commits{/sha}",
284 "comments_url": "https://api.github.com/repos/angrybayblade/ph7/comments{/number}",
285 "issue_comment_url": "https://api.github.com/repos/angrybayblade/ph7/issues/comments{/number}",
286 "contents_url": "https://api.github.com/repos/angrybayblade/ph7/contents/{+path}",
287 "compare_url": "https://api.github.com/repos/angrybayblade/ph7/compare/{base}...{head}",
288 "merges_url": "https://api.github.com/repos/angrybayblade/ph7/merges",
289 "archive_url": "https://api.github.com/repos/angrybayblade/ph7/{archive_format}{/ref}",
290 "downloads_url": "https://api.github.com/repos/angrybayblade/ph7/downloads",
291 "issues_url": "https://api.github.com/repos/angrybayblade/ph7/issues{/number}",
292 "pulls_url": "https://api.github.com/repos/angrybayblade/ph7/pulls{/number}",
293 "milestones_url": "https://api.github.com/repos/angrybayblade/ph7/milestones{/number}",
294 "notifications_url": "https://api.github.com/repos/angrybayblade/ph7/notifications{?since,all,participating}",
295 "labels_url": "https://api.github.com/repos/angrybayblade/ph7/labels{/name}",
296 "releases_url": "https://api.github.com/repos/angrybayblade/ph7/releases{/id}",
297 "deployments_url": "https://api.github.com/repos/angrybayblade/ph7/deployments",
298 "created_at": 1706936166,
299 "updated_at": "2025-03-22T17:26:27Z",
300 "pushed_at": 1750312684,
301 "git_url": "git://github.com/angrybayblade/ph7.git",
302 "ssh_url": "git@github.com:angrybayblade/ph7.git",
303 "clone_url": "https://github.com/angrybayblade/ph7.git",
304 "svn_url": "https://github.com/angrybayblade/ph7",
305 "homepage": "https://angrybayblade.github.io/ph7/",
306 "size": 3031,
307 "stargazers_count": 7,
308 "watchers_count": 7,
309 "language": "Python",
310 "has_issues": True,
311 "has_projects": True,
312 "has_downloads": True,
313 "has_wiki": True,
314 "has_pages": True,
315 "has_discussions": False,
316 "forks_count": 1,
317 "mirror_url": None,
318 "archived": False,
319 "disabled": False,
320 "open_issues_count": 0,
321 "license": None,
322 "allow_forking": True,
323 "is_template": False,
324 "web_commit_signoff_required": False,
325 "topics": [
326 "css",
327 "django",
328 "flask",
329 "html",
330 "js",
331 "template-engine",
332 "web",
333 ],
334 "visibility": "public",
335 "forks": 1,
336 "open_issues": 0,
337 "watchers": 7,
338 "default_branch": "main",
339 "stargazers": 7,
340 "master_branch": "main",
341 },
342 "pusher": {
343 "name": "angrybayblade",
344 "email": "35092918+angrybayblade@users.noreply.github.com",
345 },
346 "sender": {
347 "login": "angrybayblade",
348 "id": 35092918,
349 "node_id": "MDQ6VXNlcjM1MDkyOTE4",
350 "avatar_url": "https://avatars.githubusercontent.com/u/35092918?v=4",
351 "gravatar_id": "",
352 "url": "https://api.github.com/users/angrybayblade",
353 "html_url": "https://github.com/angrybayblade",
354 "followers_url": "https://api.github.com/users/angrybayblade/followers",
355 "following_url": "https://api.github.com/users/angrybayblade/following{/other_user}",
356 "gists_url": "https://api.github.com/users/angrybayblade/gists{/gist_id}",
357 "starred_url": "https://api.github.com/users/angrybayblade/starred{/owner}{/repo}",
358 "subscriptions_url": "https://api.github.com/users/angrybayblade/subscriptions",
359 "organizations_url": "https://api.github.com/users/angrybayblade/orgs",
360 "repos_url": "https://api.github.com/users/angrybayblade/repos",
361 "events_url": "https://api.github.com/users/angrybayblade/events{/privacy}",
362 "received_events_url": "https://api.github.com/users/angrybayblade/received_events",
363 "type": "User",
364 "user_view_type": "public",
365 "site_admin": False,
366 },
367 "created": False,
368 "deleted": False,
369 "forced": False,
370 "base_ref": None,
371 "compare": "https://github.com/angrybayblade/ph7/compare/e5eb72bc9f97...a2334682759c",
372 "commits": [
373 {
374 "id": "a2334682759c4324e911d8f52f8fb6bdf1338d94",
375 "tree_id": "ed0ae8c902cb2a0e12d3c64aea8aab66f7b06054",
376 "distinct": True,
377 "message": "temp",
378 "timestamp": "2025-06-19T11:28:01+05:30",
379 "url": "https://github.com/angrybayblade/ph7/commit/a2334682759c4324e911d8f52f8fb6bdf1338d94",
380 "author": {
381 "name": "angrybayblade",
382 "email": "vptl185@gmail.com",
383 "username": "angrybayblade",
384 },
385 "committer": {
386 "name": "angrybayblade",
387 "email": "vptl185@gmail.com",
388 "username": "angrybayblade",
389 },
390 "added": [],
391 "removed": [],
392 "modified": ["mkdocs.yml"],
393 }
394 ],
395 "head_commit": {
396 "id": "a2334682759c4324e911d8f52f8fb6bdf1338d94",
397 "tree_id": "ed0ae8c902cb2a0e12d3c64aea8aab66f7b06054",
398 "distinct": True,
399 "message": "temp",
400 "timestamp": "2025-06-19T11:28:01+05:30",
401 "url": "https://github.com/angrybayblade/ph7/commit/a2334682759c4324e911d8f52f8fb6bdf1338d94",
402 "author": {
403 "name": "angrybayblade",
404 "email": "vptl185@gmail.com",
405 "username": "angrybayblade",
406 },
407 "committer": {
408 "name": "angrybayblade",
409 "email": "vptl185@gmail.com",
410 "username": "angrybayblade",
411 },
412 "added": [],
413 "removed": [],
414 "modified": ["mkdocs.yml"],
415 },
416 },
417 "metadata": {
418 "id": "2507236e-4be2-4606-b338-fb24c76ce38d",
419 "nanoId": "ti_VZEWUqF5fQ6P",
420 "connectionId": "75271255-fe95-4d34-bee3-459a02645e38",
421 "connectionNanoId": "ca_5KdA-e2C4ZMd",
422 "triggerName": "GITHUB_COMMIT_EVENT",
423 "triggerData": '{"event_type": "push", "github_hook_id": "552965247"}',
424 "triggerConfig": {"repo": "ph7", "owner": "angrybayblade"},
425 "connection": {
426 "id": "75271255-fe95-4d34-bee3-459a02645e38",
427 "connectedAccountNanoId": "ca_5KdA-e2C4ZMd",
428 "integrationId": "500748ea-8547-4abb-9f9e-10dbcfdb81c2",
429 "authConfigNanoId": "ac_ZxnpxqOo1nAP",
430 "clientUniqueUserId": "default",
431 "status": "ACTIVE",
432 },
433 },
434 }
435
436
437 class _ChunkedTriggerEventData(te.TypedDict):
438 """Chunked trigger event data model."""
439
440 id: str
441 index: int
442 chunk: str
443 final: bool
444
445
446 class TriggerEventFilters(te.TypedDict):
447 """Trigger event filterset."""
448
449 trigger_slug: te.NotRequired[str]
450 trigger_id: te.NotRequired[str]
451 toolkit: te.NotRequired[str]
452 user_id: te.NotRequired[str]
453 auth_config_id: te.NotRequired[str]
454 connected_account_id: te.NotRequired[str]
455
456
457 TriggerCallback = t.Callable[[TriggerEvent], None]
458
459 SubscriptionErrorCallback = t.Callable[[t.Dict[str, t.Any]], None]
460
461
462 # Realtime trigger frames can carry message bodies / PII, so the raw frame is
463 # never logged in full — only a bounded preview when it fails to parse.
464 _MAX_LOGGED_FRAME_CHARS = 512
465
466
467 def _truncate_frame(event: str) -> str:
468 """Return a bounded preview of a raw frame for safe logging."""
469 if len(event) <= _MAX_LOGGED_FRAME_CHARS:
470 return event
471 return f"{event[:_MAX_LOGGED_FRAME_CHARS]}… ({len(event)} chars total)"
472
473
474 def _coerce_str(value: t.Any) -> str:
475 """Coerce a possibly-missing or non-string field to ``str``.
476
477 Mirrors the TS SDK's ``toStringOrDefault`` so realtime/webhook frames that
478 carry ``None`` or a non-string identity field don't later raise
479 ``AttributeError`` on ``.lower()`` / ``.split()``. ``None`` maps to "".
480 """
481 return "" if value is None else str(value)
482
483
484 def _is_v3_envelope(data: t.Any) -> bool:
485 """Return ``True`` if ``data`` is a modern V3 envelope.
486
487 V3 payloads carry a ``type`` starting with ``composio.`` and a ``metadata``
488 object, alongside top-level ``id`` and ``data`` keys. The same envelope is
489 delivered over both the webhook channel and the realtime (Pusher) channel,
490 so this is used to route either source through the V3 normalizer.
491 """
492 if not isinstance(data, dict):
493 return False
494 event_type = data.get("type", "")
495 return (
496 isinstance(event_type, str)
497 and event_type.startswith("composio.")
498 and isinstance(data.get("metadata"), dict)
499 and "id" in data
500 and "data" in data
501 )
502
503
504 def _build_trigger_event_from_v3(data: WebhookPayloadV3) -> TriggerEvent:
505 """Normalize a V3 envelope (webhook or realtime) into a ``TriggerEvent``.
506
507 Trigger frames are identified by their envelope ``type``
508 (``composio.trigger.message``), not by the presence of every metadata
509 field. The trigger-specific metadata fields are then read best-effort and
510 coerced to ``str`` so a frame that omits or mistypes one of them is still
511 delivered rather than silently demoted to a non-trigger event or raising
512 ``AttributeError`` on the toolkit-slug split.
513 """
514 metadata = data.get("metadata") or {}
515 event_type = data.get("type", "")
516
517 if event_type == "composio.trigger.message":
518 trigger_id = _coerce_str(metadata.get("trigger_id"))
519 trigger_slug = _coerce_str(metadata.get("trigger_slug"))
520 user_id = _coerce_str(metadata.get("user_id"))
521 connected_account_id = _coerce_str(metadata.get("connected_account_id"))
522 auth_config_id = _coerce_str(metadata.get("auth_config_id"))
523 toolkit_slug = (
524 trigger_slug.split("_")[0].upper() if "_" in trigger_slug else "UNKNOWN"
525 )
526 return t.cast(
527 TriggerEvent,
528 {
529 "id": trigger_id,
530 "uuid": trigger_id,
531 "user_id": user_id,
532 "toolkit_slug": toolkit_slug,
533 "trigger_slug": trigger_slug,
534 "metadata": {
535 "id": trigger_id,
536 "uuid": trigger_id,
537 "toolkit_slug": toolkit_slug,
538 "trigger_slug": trigger_slug,
539 "trigger_data": None,
540 "trigger_config": {},
541 "connected_account": {
542 "id": connected_account_id,
543 "uuid": connected_account_id,
544 "auth_config_id": auth_config_id,
545 "auth_config_uuid": auth_config_id,
546 "user_id": user_id,
547 "status": "ACTIVE",
548 },
549 },
550 "payload": data.get("data", {}),
551 "original_payload": None,
552 },
553 )
554
555 # Non-trigger V3 event (e.g., connection expired)
556 event_id = _coerce_str(data.get("id"))
557 return t.cast(
558 TriggerEvent,
559 {
560 "id": event_id,
561 "uuid": event_id,
562 "user_id": "",
563 "toolkit_slug": "COMPOSIO",
564 "trigger_slug": event_type,
565 "metadata": {
566 "id": event_id,
567 "uuid": event_id,
568 "toolkit_slug": "COMPOSIO",
569 "trigger_slug": event_type,
570 "trigger_data": None,
571 "trigger_config": {},
572 "connected_account": {
573 "id": "",
574 "uuid": "",
575 "auth_config_id": "",
576 "auth_config_uuid": "",
577 "user_id": "",
578 "status": "ACTIVE",
579 },
580 },
581 "payload": data.get("data", {}),
582 "original_payload": data,
583 },
584 )
585
586
587 class TriggerSubscription(Resource):
588 """Trigger subscription."""
589
590 _pusher: Pusher
591 _channel: PusherChannel
592 _connection: PusherConnection
593 _alive: bool
594
595 def __init__(self, client: HttpClient) -> None:
596 """Initialize subscription object."""
597 super().__init__(client=client)
598 self.client = client
599 self._alive = False
600 self._chunks: t.Dict[str, t.Dict[int, str]] = {}
601 self._callbacks: t.List[t.Tuple[TriggerCallback, TriggerEventFilters]] = []
602 self._on_subscription_error: t.Optional[SubscriptionErrorCallback] = None
603 self._connection_error: t.Optional[Exception] = None
604
605 def handle(
606 self, **filters: te.Unpack[TriggerEventFilters]
607 ) -> t.Callable[[TriggerCallback], TriggerCallback]:
608 """Register a trigger callaback."""
609
610 def _wrap(f: TriggerCallback) -> TriggerCallback:
611 self.logger.debug(f"Registering callback `{f.__name__}`")
612 self._callbacks.append((f, filters))
613 return f
614
615 return _wrap
616
617 def _parse_payload(self, event: str) -> t.Optional[TriggerEvent]:
618 """Parse a realtime event payload into a ``TriggerEvent``.
619
620 The realtime (Pusher) channel delivers either the modern V3 envelope
621 (for projects on webhook version V3) or the legacy envelope (for V1/V2
622 projects). Both shapes are handled here. Any unrecognized or malformed
623 frame is logged and skipped (returns ``None``) rather than raising, so a
624 single bad frame cannot tear down the subscription.
625 """
626 try:
627 data = json.loads(event)
628 except Exception as e:
629 self.logger.warning(f"Error decoding payload: {e}")
630 return None
631
632 try:
633 # V3 envelope — same shape as the V3 webhook payload.
634 if _is_v3_envelope(data):
635 return _build_trigger_event_from_v3(t.cast(WebhookPayloadV3, data))
636
637 # Legacy envelope (V1/V2 projects).
638 legacy = t.cast(_TriggerData, data)
639 return t.cast(
640 TriggerEvent,
641 {
642 "id": legacy["metadata"]["nanoId"],
643 "uuid": legacy["metadata"]["id"],
644 "user_id": legacy["metadata"]["connection"]["clientUniqueUserId"],
645 "toolkit_slug": legacy["appName"],
646 "trigger_slug": legacy["metadata"]["triggerName"],
647 "metadata": {
648 "id": legacy["metadata"]["nanoId"],
649 "uuid": legacy["metadata"]["id"],
650 "toolkit_slug": legacy["appName"],
651 "trigger_slug": legacy["metadata"]["triggerName"],
652 "trigger_data": legacy["metadata"].get("triggerData"),
653 "trigger_config": legacy["metadata"]["triggerConfig"],
654 "connected_account": {
655 "id": legacy["metadata"]["connection"][
656 "connectedAccountNanoId"
657 ],
658 "uuid": legacy["metadata"]["connection"]["id"],
659 "auth_config_id": legacy["metadata"]["connection"][
660 "authConfigNanoId"
661 ],
662 "auth_config_uuid": legacy["metadata"]["connection"][
663 "integrationId"
664 ],
665 "user_id": legacy["metadata"]["connection"][
666 "clientUniqueUserId"
667 ],
668 "status": legacy["metadata"]["connection"]["status"],
669 },
670 },
671 "payload": legacy.get("payload"),
672 "original_payload": legacy.get("originalPayload"),
673 },
674 )
675 except Exception as e:
676 # A single malformed frame must never propagate into pysher's
677 # dispatch loop (which calls callbacks with no try/except) and tear
678 # down the subscription, so catch broadly — AttributeError and
679 # others, not just KeyError/TypeError — and skip the frame.
680 self.logger.warning(f"Error parsing trigger payload: {e}")
681 return None
682
683 def _handle_chunked_events(self, event: str) -> None:
684 """Handle chunked events without letting malformed frames escape Pysher."""
685 chunk_id: t.Optional[str] = None
686 try:
687 raw_data = json.loads(event)
688 if not isinstance(raw_data, dict):
689 raise TypeError("chunked payload must be an object")
690
691 raw_id = raw_data.get("id")
692 chunk_id = raw_id if isinstance(raw_id, str) else None
693 index = raw_data.get("index")
694 chunk = raw_data.get("chunk")
695 final = raw_data.get("final")
696 if (
697 chunk_id is None
698 or not isinstance(index, int)
699 or isinstance(index, bool)
700 or not isinstance(chunk, str)
701 or not isinstance(final, bool)
702 ):
703 raise TypeError("chunked payload has invalid fields")
704
705 data = t.cast(_ChunkedTriggerEventData, raw_data)
706 if data["id"] not in self._chunks:
707 self._chunks[data["id"]] = {}
708
709 self._chunks[data["id"]][data["index"]] = data["chunk"]
710 if data["final"]:
711 _chunks = self._chunks.pop(data["id"])
712 self._handle_event(
713 event="".join([_chunks[idx] for idx in sorted(_chunks)])
714 )
715 except Exception as e:
716 if chunk_id is not None:
717 self._chunks.pop(chunk_id, None)
718 self.logger.warning(
719 f"Error parsing chunked trigger payload: {e}; "
720 f"frame: {_truncate_frame(event)}"
721 )
722
723 def _filters_match(
724 self,
725 data: TriggerEvent,
726 filters: TriggerEventFilters,
727 callback: str,
728 ) -> bool:
729 """Check if filters match the event data."""
730 checks = (
731 ("trigger_slug", data["trigger_slug"]),
732 ("trigger_id", data["metadata"]["id"]),
733 ("toolkit", data["toolkit_slug"]),
734 ("user_id", data["user_id"]),
735 ("auth_config_id", data["metadata"]["connected_account"]["auth_config_id"]),
736 ("connected_account_id", data["metadata"]["connected_account"]["id"]),
737 )
738 for name, check in checks:
739 value = filters.get(name)
740 if value is None:
741 # No filter set for this field — nothing to match against.
742 continue
743
744 # ``check`` is str()-wrapped because realtime frames may carry
745 # non-string identity fields; an empty event-side value is treated
746 # as a non-match so synthesized "" fields don't fail open into a
747 # filter that happens to be "".
748 check_str = str(check)
749 if check_str and str(value).lower() == check_str.lower():
750 continue
751
752 # Payloads don't carry the toolkit slug, so ``toolkit_slug`` is the
753 # trigger slug's first ``_`` segment, which is wrong for toolkits
754 # whose slug contains an underscore (``ONE_DRIVE_FILE_CREATED_TRIGGER``
755 # gives ``ONE``). Trigger slugs start with ``<TOOLKIT>_``, so the
756 # toolkit filter also matches on that prefix.
757 if (
758 name == "toolkit"
759 and str(value)
760 and str(data["trigger_slug"])
761 .lower()
762 .startswith(f"{str(value).lower()}_")
763 ):
764 continue
765
766 self.logger.debug(
767 f"Skipping `{callback}` since "
768 f"`{name}` filter does not match the event metadata",
769 )
770 return False
771 return True
772
773 def _handle_callback(
774 self,
775 callback: TriggerCallback,
776 data: TriggerEvent,
777 filters: TriggerEventFilters,
778 ) -> t.Any:
779 """Handle callback."""
780 if not self._filters_match(data, filters, callback.__name__):
781 return
782
783 try:
784 callback(data)
785 except Exception:
786 self.logger.error(
787 f"Error executing `{callback.__name__}` for "
788 f"event `{data['metadata']['trigger_slug']}` "
789 f"with error:\n {traceback.format_exc()}"
790 )
791
792 def _handle_event(self, event: str) -> None:
793 """Filter events and call the callback function."""
794 data = self._parse_payload(event=event)
795 if data is None:
796 # _parse_payload already logged the specific reason; here we only
797 # note that the frame was skipped, with a bounded preview so a
798 # PII-bearing frame isn't dumped in full.
799 self.logger.error(
800 f"Skipping unparseable trigger frame: {_truncate_frame(event)}"
801 )
802 return
803
804 self.logger.debug(
805 f"Received trigger event with trigger ID: {data['metadata']['id']} "
806 f"and trigger name: {data['metadata']['trigger_slug']}"
807 )
808 awaitables: t.List = []
809 with ThreadPoolExecutor() as executor:
810 for callback, filters in self._callbacks:
811 awaitables.append(
812 executor.submit(
813 self._handle_callback,
814 callback,
815 data,
816 filters,
817 )
818 )
819 _ = [future.result() for future in awaitables]
820
821 def _fail_subscription(self, error: Exception) -> None:
822 """Record an establish-time subscription failure and notify the callback.
823
824 Used for failures that happen before any channel event can fire:
825 pysher performs the channel-auth request synchronously inside
826 ``pusher.subscribe()``, so auth failures raise on the websocket thread
827 instead of arriving as ``pusher:subscription_error`` frames. The
828 pending ``connect()`` wait loop re-raises the recorded error instead
829 of spinning to its timeout.
830 """
831 self.logger.error(f"Trigger subscription error: {error}")
832 self._connection_error = error
833 callback = self._on_subscription_error
834 if callback is None:
835 return
836 try:
837 callback({"error": str(error)})
838 except Exception:
839 self.logger.error(
840 f"Error in subscription error callback:\n {traceback.format_exc()}"
841 )
842
843 def _raise_on_connection_error(self) -> None:
844 """Raise the recorded establish-time failure, if any."""
845 error = self._connection_error
846 if error is not None:
847 raise error
848
849 def _handle_subscription_error(self, event: str) -> None:
850 """Handle a ``pusher:subscription_error`` frame.
851
852 Logs the failure at the SDK boundary and invokes the optional
853 ``on_subscription_error`` callback registered through
854 ``Triggers.subscribe``. Callback exceptions are contained and logged
855 so a faulty handler cannot tear down the pysher dispatch thread
856 (pysher invokes bound callbacks without a try/except).
857 """
858 self.logger.error(f"Trigger subscription error: {_truncate_frame(event)}")
859 callback = self._on_subscription_error
860 if callback is None:
861 return
862 try:
863 payload: t.Dict[str, t.Any] = json.loads(event)
864 except Exception:
865 payload = {"raw": event}
866 try:
867 callback(payload)
868 except Exception:
869 self.logger.error(
870 f"Error in subscription error callback:\n {traceback.format_exc()}"
871 )
872
873 def is_alive(self) -> bool:
874 """Check if subscription is live."""
875 return self._alive
876
877 def has_errored(self) -> bool:
878 """Check if the connection errored and disconnected.
879
880 This follows pysher's own lifecycle instead of websocket-client's
881 ``has_errored`` flag. That flag stays set through pysher's reconnect
882 backoff (and, on websocket-client 1.9.0 and older, for the rest of
883 the reused socket), so it cannot tell a drop pysher will recover
884 from apart from a connection pysher has given up on. pysher's
885 connection thread stays alive across reconnects and exits once the
886 connection is dead for good (unrecoverable ``pusher:error``, or
887 ``stop()``), which is exactly when ``wait_forever`` should return.
888 """
889 connection = getattr(self, "_connection", None)
890 if connection is None:
891 return True
892 return not connection.is_alive()
893
894 def set_alive(self) -> None:
895 """Set `_alive` to True."""
896 self._alive = True
897
898 def wait_forever(self) -> None:
899 """Wait until stopped or the connection worker exits.
900
901 Recoverable connection failures keep waiting while pysher retries,
902 including throughout an extended network outage.
903 """
904 while self.is_alive() and not self.has_errored():
905 time.sleep(1)
906
907 def stop(self) -> None:
908 """Stop the trigger listener.
909
910 ``_alive`` is cleared first so a main thread parked in
911 ``wait_forever`` unblocks immediately. The connection disconnect is
912 then run off the calling thread: ``pysher.Connection.disconnect`` does
913 ``socket.close(); join(timeout)`` on the websocket thread, but the
914 documented usage runs ``stop()`` from inside a trigger callback, which
915 pysher dispatches on that very websocket thread (``_handle_event``
916 blocks on the callback's ``future.result()``). Joining the thread from
917 a callback that runs on it deadlocks the whole process. Tearing the
918 connection down on a background thread breaks that reentrancy while
919 still ensuring the socket is closed.
920 """
921 self._alive = False
922 thread = threading.Thread(
923 target=self._connection.disconnect,
924 name="composio-trigger-disconnect",
925 daemon=True,
926 )
927 thread.start()
928
929 def restart(self) -> None:
930 """Request a reconnect on the running subscription worker."""
931 # Disconnect joins the worker; calling _connect afterwards runs the
932 # socket on the caller while has_errored sees a terminated worker.
933 self._connection.reconnect(reconnect_interval=0)
934
935
936 def _silent_pysher_logger() -> logging.Logger:
937 """A logger that swallows pysher's connection chatter.
938
939 pysher logs every raw websocket frame at ``INFO``, trigger payloads
940 included. Handing its connection a logger that neither emits nor propagates
941 keeps those frames out of the user's log output; the SDK logs what it needs
942 itself from ``TriggerSubscription``.
943 """
944 logger = logging.getLogger(_PYSHER_LOGGER_NAME)
945 if not any(isinstance(handler, logging.NullHandler) for handler in logger.handlers):
946 logger.addHandler(logging.NullHandler())
947 logger.propagate = False
948 logger.setLevel(logging.CRITICAL)
949 logger.disabled = True
950 return logger
951
952
953 def _validate_pusher_cluster(cluster: object) -> str:
954 """Return ``cluster`` once it is known to be a plain cluster label.
955
956 :raises InvalidPusherClusterError: naming the shape violation, never the
957 value itself, since the response that carried it is untrusted.
958 """
959 if not isinstance(cluster, str) or not cluster:
960 raise exceptions.InvalidPusherClusterError(
961 "Realtime credentials did not include a pusher cluster"
962 )
963 if len(cluster) > _PUSHER_CLUSTER_MAX_LENGTH:
964 raise exceptions.InvalidPusherClusterError(
965 "Realtime credentials returned a pusher cluster longer than "
966 f"{_PUSHER_CLUSTER_MAX_LENGTH} characters"
967 )
968 if _PUSHER_CLUSTER_PATTERN.match(cluster) is None:
969 raise exceptions.InvalidPusherClusterError(
970 "Realtime credentials returned a pusher cluster with characters "
971 "outside [a-z0-9-]"
972 )
973 return cluster
974
975
976 class _ComposioPusher(Pusher):
977 """``pysher.Pusher`` with a bounded, typed channel-auth request.
978
979 pysher's own ``_generate_auth_token``/``_generate_presence_token`` POST to
980 the auth endpoint with no timeout and turn a non-200 into a bare
981 ``AssertionError``, on the websocket thread, on every (re)subscribe. Both
982 are replaced here: the request carries :data:`PUSHER_AUTH_TIMEOUT`, and any
983 failure surfaces as :class:`~composio.exceptions.TriggerSubscriptionAuthError`.
984
985 The endpoint is the Composio API base URL the client was configured with,
986 a fixed trusted host rather than a value from a response, so the request
987 is a plain ``requests.post`` instead of going through the SSRF guard.
988 """
989
990 def _generate_auth_token(self, channel_name: str) -> str:
991 if self.secret or not self.auth_endpoint:
992 return t.cast(str, super()._generate_auth_token(channel_name))
993 return self._request_channel_auth(
994 {"channel_name": channel_name, "socket_id": self.connection.socket_id}
995 )
996
997 def _generate_presence_token(self, channel_name: str) -> str:
998 if self.secret or not self.auth_endpoint:
999 return t.cast(str, super()._generate_presence_token(channel_name))
1000 return self._request_channel_auth(
1001 {
1002 "channel_name": channel_name,
1003 "socket_id": self.connection.socket_id,
1004 "user_data": self.user_data,
1005 }
1006 )
1007
1008 def _request_channel_auth(self, request_data: t.Dict[str, t.Any]) -> str:
1009 try:
1010 response = requests.post(
1011 self.auth_endpoint,
1012 data=request_data,
1013 headers=self.auth_endpoint_headers,
1014 timeout=PUSHER_AUTH_TIMEOUT,
1015 )
1016 except requests.RequestException as error:
1017 raise exceptions.TriggerSubscriptionAuthError(
1018 f"Could not reach the realtime auth endpoint: {type(error).__name__}"
1019 ) from error
1020
1021 if response.status_code != 200:
1022 raise exceptions.TriggerSubscriptionAuthError(
1023 f"Realtime channel auth failed with HTTP {response.status_code}"
1024 )
1025
1026 try:
1027 auth = response.json()["auth"]
1028 except (ValueError, KeyError, TypeError) as error:
1029 raise exceptions.TriggerSubscriptionAuthError(
1030 "Realtime channel auth response did not carry an `auth` token"
1031 ) from error
1032 if not isinstance(auth, str) or not auth:
1033 raise exceptions.TriggerSubscriptionAuthError(
1034 "Realtime channel auth response did not carry an `auth` token"
1035 )
1036 return auth
1037
1038
1039 class _SubcriptionBuilder(WithLogger):
1040 """Pusher client for Composio SDK."""
1041
1042 def __init__(self, client: HttpClient) -> None:
1043 """Initialize pusher client."""
1044 super().__init__()
1045 self._client = client
1046 self.base_url = self._client.base_url
1047 self.internal = Internal(client=self._client)
1048 self.subscription = TriggerSubscription(client=self._client)
1049
1050 def _get_connection_handler(
1051 self,
1052 project_id: str,
1053 pusher: Pusher,
1054 subscription: TriggerSubscription,
1055 ) -> t.Callable[[str], None]:
1056 def _connection_handler(_: str) -> None:
1057 try:
1058 channel = t.cast(
1059 PusherChannel,
1060 pusher.subscribe(
1061 channel_name=f"private-{project_id}_triggers",
1062 ),
1063 )
1064 except Exception as e:
1065 # pysher performs the channel-auth request synchronously inside
1066 # ``subscribe()``: an auth failure raises here on the websocket
1067 # thread before ``pusher:subscription_error`` can fire or
1068 # ``set_alive()`` can run. Surface it through the error path
1069 # and let the pending ``connect()`` fail fast; the wait loop's
1070 # teardown disconnects the pusher.
1071 subscription._fail_subscription(e) # pylint: disable=protected-access
1072 return
1073 channel.bind(
1074 event_name="trigger_to_client",
1075 callback=subscription._handle_event,
1076 )
1077 channel.bind(
1078 event_name="chunked-trigger_to_client",
1079 callback=subscription._handle_chunked_events,
1080 )
1081 channel.bind(
1082 event_name="pusher:subscription_error",
1083 callback=subscription._handle_subscription_error,
1084 )
1085 subscription.set_alive()
1086 subscription._channel = channel # pylint: disable=protected-access
1087 subscription._connection = ( # pylint: disable=protected-access
1088 channel.connection
1089 )
1090
1091 return _connection_handler
1092
1093 def _get_pusher_instance(self, key: str, cluster: str) -> Pusher:
1094 """Get a pusher instance."""
1095 return _ComposioPusher(
1096 key=key,
1097 cluster=_validate_pusher_cluster(cluster),
1098 auth_endpoint=PUSHER_AUTH_URL.format(base_url=self._client.base_url),
1099 auth_endpoint_headers={
1100 **credential_headers(self._client),
1101 "x-request-id": str(uuid.uuid4()),
1102 },
1103 auto_sub=True,
1104 )
1105
1106 def connect(
1107 self,
1108 timeout: float = 15.0,
1109 on_subscription_error: t.Optional[SubscriptionErrorCallback] = None,
1110 ) -> TriggerSubscription:
1111 """Connect to Pusher channel for given client ID."""
1112 self.logger.debug("Creating trigger subscription")
1113 project_info = self.internal.get_sdk_realtime_credentials()
1114 pusher = self._get_pusher_instance(
1115 key=project_info.pusher_key,
1116 cluster=project_info.pusher_cluster,
1117 )
1118
1119 # pysher logs every raw frame at INFO; keep them out of user logs.
1120 pusher.connection.logger = _silent_pysher_logger()
1121 pusher.connection.bind(
1122 "pusher:connection_established",
1123 self._get_connection_handler(
1124 project_id=project_info.project_id,
1125 pusher=pusher,
1126 subscription=self.subscription,
1127 ),
1128 )
1129 # Set before ``pusher.connect()``: the subscription_error handler runs
1130 # on pysher's websocket thread once the channel subscribes, so the
1131 # callback must already be in place.
1132 self.subscription._on_subscription_error = ( # pylint: disable=protected-access
1133 on_subscription_error
1134 )
1135 pusher.connect()
1136
1137 # Wait for connection to get established. On timeout, tear down the
1138 # connection before raising: pysher's run loop reconnects every
1139 # ``reconnect_interval`` until ``disconnect`` is called, so a plain
1140 # raise would leak a websocket thread (and, if it eventually connects,
1141 # silently subscribe a forgotten channel) for the life of the process.
1142 deadline = time.time() + timeout
1143 try:
1144 while time.time() < deadline:
1145 self.subscription._raise_on_connection_error() # pylint: disable=protected-access
1146 if not self.subscription.is_alive():
1147 time.sleep(0.5)
1148 continue
1149
1150 self.subscription._pusher = pusher # pylint: disable=protected-access
1151 return self.subscription
1152 raise ComposioSDKTimeoutError(
1153 "Timed out while waiting for trigger listener to be established"
1154 )
1155 except Exception:
1156 pusher.disconnect()
1157 raise
1158
1159
1160 class Triggers(Resource):
1161 """Triggers (instance) class"""
1162
1163 enable: t.Callable
1164 """Enables a trigger given its id"""
1165
1166 disable: t.Callable
1167 """Disables a trigger given its id"""
1168
1169 def __init__(
1170 self,
1171 client: HttpClient,
1172 toolkit_versions: t.Optional[ToolkitVersionParam] = None,
1173 ):
1174 """
1175 Initialize the triggers resource.
1176
1177 :param client: The client to use for the triggers resource.
1178 :param toolkit_versions: The versions of the toolkits to use. Defaults to 'latest' if not provided.
1179 """
1180 self._client = client
1181 self._toolkit_versions = toolkit_versions
1182 self.list_enum = self._client.triggers_types.retrieve_enum
1183 self.delete = self._client.trigger_instances.manage.delete
1184 self.enable = functools.partial(
1185 self._client.trigger_instances.manage.update,
1186 status="enable",
1187 )
1188 self.disable = functools.partial(
1189 self._client.trigger_instances.manage.update,
1190 status="disable",
1191 )
1192
1193 def set_webhook_subscription(
1194 self,
1195 *,
1196 webhook_url: str,
1197 enabled_events: t.Optional[t.Sequence[str]] = None,
1198 version: t.Union[WebhookVersion, str] = WebhookVersion.V3,
1199 ) -> WebhookSubscription:
1200 """
1201 Create or update the project webhook subscription used for webhook delivery.
1202
1203 If a subscription already exists, the first subscription is updated. Otherwise a
1204 new subscription is created. By default this subscribes to V3 trigger message
1205 events.
1206
1207 Example:
1208 composio.triggers.set_webhook_subscription(
1209 webhook_url=f"{APP_URL}/webhooks/composio",
1210 )
1211 """
1212 return WebhookSubscriptions(client=self._client).set(
1213 webhook_url=webhook_url,
1214 enabled_events=enabled_events,
1215 version=version,
1216 )
1217
1218 def get_type(self, slug: str) -> TriggersTypeRetrieveResponse:
1219 """
1220 Get a trigger type by its slug
1221 Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version
1222
1223 :param slug: The slug of the trigger type
1224 :return: The trigger type
1225 """
1226 return self._client.triggers_types.retrieve(
1227 slug=slug, toolkit_versions=none_to_omit(self._toolkit_versions)
1228 )
1229
1230 def list_active(
1231 self,
1232 trigger_ids: t.Optional[list[str]] = None,
1233 trigger_names: t.Optional[list[str]] = None,
1234 auth_config_ids: t.Optional[list[str]] = None,
1235 connected_account_ids: t.Optional[list[str]] = None,
1236 show_disabled: t.Optional[bool] = None,
1237 limit: t.Optional[int] = None,
1238 cursor: t.Optional[str] = None,
1239 ):
1240 """
1241 List all active triggers
1242
1243 :param trigger_ids: List of trigger IDs to filter by
1244 :param trigger_names: List of trigger names to filter by
1245 :param auth_config_ids: List of auth config IDs to filter by
1246 :param connected_account_ids: List of connected account IDs to filter by
1247 :param show_disabled: Whether to show disabled triggers
1248 :param limit: Limit the number of triggers to return
1249 :param cursor: Cursor for pagination. Use the nextCursor from the response to get the next page.
1250 :return: List of active triggers
1251 """
1252 return self._client.trigger_instances.list_active(
1253 query_trigger_ids_1=trigger_ids,
1254 query_trigger_names_1=trigger_names,
1255 query_auth_config_ids_1=auth_config_ids,
1256 query_connected_account_ids_1=connected_account_ids,
1257 query_show_disabled_1=show_disabled,
1258 limit=limit if limit is not None else omit,
1259 cursor=cursor if cursor is not None else omit,
1260 )
1261
1262 def list(
1263 self,
1264 *,
1265 cursor: t.Optional[str] = None,
1266 limit: t.Optional[int] = None,
1267 toolkit_slugs: t.Optional[list[str]] = None,
1268 ):
1269 """
1270 List all the trigger types.
1271
1272 :param cursor: The cursor for pagination
1273 :param limit: The maximum number of trigger types to return
1274 :param toolkit_slugs: Filter by toolkit slugs
1275 :return: The list of trigger types
1276 """
1277 return self._client.triggers_types.list(
1278 cursor=none_to_omit(cursor),
1279 limit=none_to_omit(limit),
1280 toolkit_slugs=none_to_omit(toolkit_slugs),
1281 toolkit_versions=none_to_omit(self._toolkit_versions),
1282 )
1283
1284 @t.overload
1285 def create(
1286 self,
1287 slug: str,
1288 *,
1289 connected_account_id: str,
1290 trigger_config: t.Optional[t.Dict[str, t.Any]] = None,
1291 type: t.Optional[t.Literal["webhook", "poll"]] = None,
1292 polling_interval: t.Optional[int] = None,
1293 ) -> trigger_instance_upsert_response.TriggerInstanceUpsertResponse: ...
1294
1295 @t.overload
1296 def create(
1297 self,
1298 slug: str,
1299 *,
1300 user_id: str,
1301 trigger_config: t.Optional[t.Dict[str, t.Any]] = None,
1302 type: t.Optional[t.Literal["webhook", "poll"]] = None,
1303 polling_interval: t.Optional[int] = None,
1304 ) -> trigger_instance_upsert_response.TriggerInstanceUpsertResponse: ...
1305
1306 def create(
1307 self,
1308 slug: str,
1309 *,
1310 user_id: t.Optional[str] = None,
1311 connected_account_id: t.Optional[str] = None,
1312 trigger_config: t.Optional[t.Dict[str, t.Any]] = None,
1313 type: t.Optional[t.Literal["webhook", "poll"]] = None,
1314 polling_interval: t.Optional[int] = None,
1315 ) -> trigger_instance_upsert_response.TriggerInstanceUpsertResponse:
1316 """
1317 Create a trigger instance
1318
1319 :param slug: The slug of the trigger
1320 :param user_id: The ID of the user that owns the connected account. When
1321 ``connected_account_id`` is omitted, the backend resolves the first
1322 active connection for this user and the trigger's toolkit.
1323 :param connected_account_id: The ID of the connected account to pin
1324 :param trigger_config: The configuration of the trigger
1325 :param type: ``webhook`` or ``poll``, for a trigger that supports both.
1326 Omit it to let Composio choose.
1327 :param polling_interval: Minutes between polls, for an instance that polls.
1328 Wins over ``trigger_config["interval"]``.
1329 :return: The trigger instance, with the ``type`` it uses, the
1330 ``fallback_reason`` when it polls after a webhook was unavailable, and
1331 its ``polling_interval``
1332 """
1333 # Treat blank strings as missing so an empty or whitespace-only
1334 # `user_id` / `connected_account_id` does not slip past the guard below
1335 # or reach the backend (parity with the TypeScript SDK's `userId` check).
1336 if isinstance(user_id, str) and not user_id.strip():
1337 user_id = None
1338 if isinstance(connected_account_id, str) and not connected_account_id.strip():
1339 connected_account_id = None
1340
1341 if user_id is None and connected_account_id is None:
1342 raise exceptions.InvalidParams(
1343 "please provide valid `connected_account_id` or `user_id`"
1344 )
1345
1346 # Validate the trigger slug up-front so callers get a clear
1347 # `TriggerTypeNotFound` (parity with the TypeScript SDK).
1348 try:
1349 self.get_type(slug=slug)
1350 except APIStatusError as error:
1351 if error.status_code in (400, 404):
1352 raise exceptions.TriggerTypeNotFound(
1353 f"Trigger type {slug} not found"
1354 ) from error
1355 raise
1356
1357 # Pass user_id straight through: when connected_account_id is omitted the
1358 # backend resolves the first active connection for this user and the
1359 # trigger's toolkit (parity with tool execution). When 2FA is enabled and
1360 # connected_account_id is pinned, the backend validates that user_id owns it.
1361 return self._client.trigger_instances.upsert(
1362 slug=slug,
1363 connected_account_id=none_to_omit(connected_account_id),
1364 toolkit_versions=self._toolkit_versions,
1365 body_trigger_config_1=none_to_omit(trigger_config),
1366 type=none_to_omit(type),
1367 polling_interval=none_to_omit(polling_interval),
1368 user_id=none_to_omit(user_id),
1369 )
1370
1371 def subscribe(
1372 self,
1373 timeout: float = 15.0,
1374 on_subscription_error: t.Optional[SubscriptionErrorCallback] = None,
1375 ) -> TriggerSubscription:
1376 """
1377 Subscribe to a trigger and receive trigger events.
1378
1379 :param timeout: The timeout to wait for the subscription to be established.
1380 :param on_subscription_error: Optional callback invoked when the channel
1381 subscription fails: with the raw Pusher payload for asynchronous
1382 ``pusher:subscription_error`` events (for example a later permission
1383 rejection), or with ``{"error": ...}`` for failures raised while
1384 establishing the subscription (for example an auth rejection —
1385 pysher performs channel auth synchronously). Establish-time failures
1386 also make ``subscribe()`` raise the underlying error promptly
1387 instead of waiting out the timeout. Exceptions raised inside the
1388 callback are contained and logged, never rethrown.
1389 :return: The trigger subscription handler.
1390 """
1391 return _SubcriptionBuilder(client=self._client).connect(
1392 timeout=timeout,
1393 on_subscription_error=on_subscription_error,
1394 )
1395
1396 def verify_webhook(
1397 self,
1398 *,
1399 id: str,
1400 payload: str,
1401 secret: str,
1402 signature: str,
1403 timestamp: str,
1404 tolerance: int = 300,
1405 ) -> VerifyWebhookResult:
1406 """
1407 Verify an incoming webhook payload and signature.
1408
1409 This method validates that the webhook request is authentic by:
1410 1. Validating the webhook timestamp is within the tolerance window
1411 2. Verifying the HMAC-SHA256 signature using the correct algorithm
1412 3. Parsing the payload and detecting the webhook version (V1, V2, or V3)
1413
1414 :param id: The webhook message ID from the 'webhook-id' header (format: 'msg_xxx')
1415 :param payload: The raw webhook payload as a string (request body)
1416 :param secret: The webhook secret used to sign the payload (from Composio dashboard)
1417 :param signature: The signature from the 'webhook-signature' header (format: 'v1,base64EncodedSignature')
1418 :param timestamp: The webhook timestamp from the 'webhook-timestamp' header (Unix seconds)
1419 :param tolerance: Maximum allowed age of the webhook in seconds (default: 300 = 5 minutes).
1420 Set to 0 to disable timestamp validation.
1421 :return: VerifyWebhookResult containing version, normalized payload, and raw payload
1422 :raises WebhookSignatureVerificationError: If the signature verification fails
1423 :raises WebhookPayloadError: If the payload cannot be parsed or is invalid
1424
1425 Example:
1426 # In a Flask webhook handler
1427 @app.route('/webhook', methods=['POST'])
1428 def webhook():
1429 try:
1430 result = composio.triggers.verify_webhook(
1431 id=request.headers.get('webhook-id', ''),
1432 payload=request.get_data(as_text=True),
1433 signature=request.headers.get('webhook-signature', ''),
1434 timestamp=request.headers.get('webhook-timestamp', ''),
1435 secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
1436 )
1437
1438 # Process the verified payload
1439 print(f"Version: {result['version']}")
1440 print(f"Received trigger: {result['payload']['trigger_slug']}")
1441 return 'OK', 200
1442 except WebhookSignatureVerificationError:
1443 return 'Unauthorized', 401
1444 """
1445 # Validate timestamp if tolerance is set
1446 if tolerance > 0:
1447 self._validate_webhook_timestamp_header(timestamp, tolerance)
1448
1449 # Verify signature using the correct algorithm
1450 self._verify_webhook_signature(
1451 webhook_id=id,
1452 webhook_timestamp=timestamp,
1453 payload=payload,
1454 signature=signature,
1455 secret=secret,
1456 )
1457
1458 # Parse and detect version
1459 version, raw_payload, normalized_payload = self._parse_webhook_payload(payload)
1460
1461 return {
1462 "version": version,
1463 "payload": normalized_payload,
1464 "raw_payload": raw_payload,
1465 }
1466
1467 def parse(
1468 self,
1469 request: t.Any = None,
1470 *,
1471 body: t.Union[str, bytes, t.Mapping[str, t.Any], None] = None,
1472 headers: t.Union[t.Mapping[str, t.Any], None] = None,
1473 verify_secret: t.Union[str, None, Omit] = omit,
1474 tolerance: int = 300,
1475 ) -> VerifyWebhookResult:
1476 """
1477 Parse an incoming webhook request into a typed, normalized trigger payload.
1478
1479 Pass a framework request object, or pass ``body=`` and ``headers=``
1480 explicitly. When ``verify_secret`` is provided, the SDK verifies the
1481 webhook signature before returning the normalized trigger payload. When
1482 it is omitted, the SDK parses the body without verifying the signature.
1483
1484 ``request`` may be any object exposing the request body and headers, such
1485 as a Flask, Django, or FastAPI request. The body is read from ``.body``
1486 (or ``.data`` / ``.get_data()``), and the headers are read from
1487 ``.headers``. Because this SDK is synchronous, async frameworks must pass
1488 an already-read raw body, for example via ``body=await request.body()``.
1489
1490 :param request: The incoming webhook request object (Flask/Django/FastAPI)
1491 :param body: The raw request body (str/bytes/parsed mapping); overrides ``request``
1492 :param headers: The request headers as a mapping; overrides ``request``
1493 :param verify_secret: Webhook secret; when set, the signature is verified.
1494 Omit it entirely to parse without verification. Passing a present-but-empty
1495 value (e.g. an unset ``COMPOSIO_WEBHOOK_SECRET``) raises rather than
1496 silently skipping verification.
1497 :param tolerance: Max webhook age in seconds (only used when verifying)
1498 :return: VerifyWebhookResult containing version, normalized payload, and raw payload
1499 :raises ValidationError: If ``verify_secret`` is empty, or is set but signature headers are missing
1500 :raises WebhookSignatureVerificationError: If signature verification fails
1501 :raises WebhookPayloadError: If the payload cannot be parsed
1502
1503 Example:
1504 # Flask: verify the signature
1505 @app.route('/webhooks/composio', methods=['POST'])
1506 def webhook():
1507 try:
1508 result = composio.triggers.parse(
1509 request,
1510 verify_secret=os.environ['COMPOSIO_WEBHOOK_SECRET'],
1511 )
1512 print(f"Trigger: {result['payload']['trigger_slug']}")
1513 print(f"Event data: {result['payload']['payload']}")
1514 return 'OK', 200
1515 except exceptions.WebhookSignatureVerificationError:
1516 return 'Unauthorized', 401
1517
1518 # FastAPI: parse without verifying after reading the async body
1519 @app.post('/webhooks/composio')
1520 async def webhook(request: Request):
1521 raw = await request.body()
1522 result = composio.triggers.parse(body=raw, headers=request.headers)
1523 return {'trigger': result['payload']['trigger_slug']}
1524 """
1525 raw_body = body if body is not None else self._extract_request_body(request)
1526 raw_headers = (
1527 headers if headers is not None else getattr(request, "headers", None)
1528 )
1529
1530 payload = self._body_to_str(raw_body)
1531
1532 # Distinguish "caller omitted verify_secret" (explicit opt-out) from
1533 # "caller passed verify_secret but it resolved to empty" (almost always
1534 # an unset COMPOSIO_WEBHOOK_SECRET). The latter must fail loudly rather
1535 # than silently skip verification and accept forged events.
1536 if isinstance(verify_secret, Omit):
1537 version, raw_payload, normalized_payload = self._parse_webhook_payload(
1538 payload
1539 )
1540 return {
1541 "version": version,
1542 "payload": normalized_payload,
1543 "raw_payload": raw_payload,
1544 }
1545
1546 if not verify_secret:
1547 raise exceptions.ValidationError(
1548 "Cannot verify webhook: `verify_secret` was provided but is empty — "
1549 "your COMPOSIO_WEBHOOK_SECRET is likely unset. Set the secret, or omit "
1550 "`verify_secret` entirely to parse without verification."
1551 )
1552
1553 # Secret provided: signature headers are required to verify.
1554 webhook_id = self._get_header(raw_headers, "webhook-id")
1555 timestamp = self._get_header(raw_headers, "webhook-timestamp")
1556 signature = self._get_header(raw_headers, "webhook-signature")
1557
1558 missing = [
1559 name
1560 for name, value in (
1561 ("webhook-id", webhook_id),
1562 ("webhook-timestamp", timestamp),
1563 ("webhook-signature", signature),
1564 )
1565 if not value
1566 ]
1567 if missing:
1568 raise exceptions.ValidationError(
1569 "Cannot verify webhook: missing signature header(s) "
1570 f"{', '.join(repr(name) for name in missing)}. "
1571 "Pass the raw, unparsed request body and ensure the Composio "
1572 "signature headers (webhook-id, webhook-timestamp, "
1573 "webhook-signature) are forwarded to triggers.parse(). "
1574 "To parse without verifying, omit `verify_secret`."
1575 )
1576
1577 return self.verify_webhook(
1578 id=t.cast(str, webhook_id),
1579 payload=payload,
1580 secret=verify_secret,
1581 signature=t.cast(str, signature),
1582 timestamp=t.cast(str, timestamp),
1583 tolerance=tolerance,
1584 )
1585
1586 @staticmethod
1587 def _extract_request_body(request: t.Any) -> t.Union[str, bytes, None]:
1588 """Read the raw body from a framework request object.
1589
1590 Tries the common attributes used by Flask (``get_data``/``data``),
1591 Django (``body``) and similar. Returns ``None`` when nothing usable is
1592 found so the caller surfaces a clear parse error.
1593 """
1594 if request is None:
1595 return None
1596
1597 # Flask: request.get_data() returns the raw body bytes.
1598 get_data = getattr(request, "get_data", None)
1599 if callable(get_data):
1600 return get_data()
1601
1602 for attr in ("body", "data"):
1603 value = getattr(request, attr, None)
1604 if value is not None and not callable(value):
1605 return value
1606
1607 return None
1608
1609 @staticmethod
1610 def _body_to_str(body: t.Union[str, bytes, t.Mapping[str, t.Any], None]) -> str:
1611 """Coerce a body (str, bytes, parsed mapping, or None) into a raw string."""
1612 if body is None:
1613 return ""
1614 if isinstance(body, str):
1615 return body
1616 if isinstance(body, (bytes, bytearray)):
1617 return bytes(body).decode("utf-8")
1618 # Already-parsed mapping (e.g. a framework that pre-parsed JSON). Note:
1619 # re-serializing cannot reproduce the exact signed bytes, so signature
1620 # verification on a pre-parsed body is best-effort only.
1621 return json.dumps(body)
1622
1623 @staticmethod
1624 def _get_header(headers: t.Any, name: str) -> t.Optional[str]:
1625 """Read a header value case-insensitively from a headers mapping.
1626
1627 Supports both plain ``dict`` headers and framework header objects
1628 (Werkzeug/Django ``HttpHeaders``) that expose a ``get`` method, which is
1629 already case-insensitive.
1630 """
1631 if headers is None:
1632 return None
1633
1634 get = getattr(headers, "get", None)
1635 if callable(get):
1636 value = get(name)
1637 if value is not None:
1638 return str(value)
1639
1640 # Fall back to a manual case-insensitive scan for plain mappings.
1641 try:
1642 items = headers.items()
1643 except AttributeError:
1644 return None
1645
1646 target = name.lower()
1647 for key, value in items:
1648 if isinstance(key, str) and key.lower() == target:
1649 return str(value) if value is not None else None
1650 return None
1651
1652 def _verify_webhook_signature(
1653 self,
1654 *,
1655 webhook_id: str,
1656 webhook_timestamp: str,
1657 payload: str,
1658 signature: str,
1659 secret: str,
1660 ) -> None:
1661 """
1662 Verify the HMAC-SHA256 signature of a webhook payload.
1663
1664 The signature is computed as: HMAC-SHA256(webhookId.webhookTimestamp.payload, secret)
1665 and then base64 encoded with a 'v1,' prefix.
1666
1667 :param webhook_id: The webhook message ID from header
1668 :param webhook_timestamp: The webhook timestamp from header
1669 :param payload: The raw webhook payload
1670 :param signature: The signature to verify (format: 'v1,base64EncodedSignature')
1671 :param secret: The webhook secret
1672 :raises WebhookSignatureVerificationError: If verification fails
1673 """
1674 if not payload:
1675 raise exceptions.WebhookSignatureVerificationError(
1676 "No webhook payload was provided."
1677 )
1678
1679 if not signature:
1680 raise exceptions.WebhookSignatureVerificationError(
1681 "No signature header value was provided. "
1682 "Please pass the value of the webhook signature header."
1683 )
1684
1685 if not secret:
1686 raise exceptions.WebhookSignatureVerificationError(
1687 "No webhook secret was provided. "
1688 "You can find your webhook secret in your Composio dashboard."
1689 )
1690
1691 if not webhook_id:
1692 raise exceptions.WebhookSignatureVerificationError(
1693 "No webhook ID was provided. "
1694 "Please pass the value of the 'webhook-id' header."
1695 )
1696
1697 if not webhook_timestamp:
1698 raise exceptions.WebhookSignatureVerificationError(
1699 "No webhook timestamp was provided. "
1700 "Please pass the value of the 'webhook-timestamp' header."
1701 )
1702
1703 # Parse signature header - format is "v1,base64Sig" or "v1,sig1 v1,sig2"
1704 # Split by space to handle multiple signatures
1705 signature_parts = signature.split(" ")
1706 v1_signatures: t.List[str] = []
1707
1708 for part in signature_parts:
1709 if part.startswith("v1,"):
1710 v1_signatures.append(part[3:]) # Remove "v1," prefix
1711
1712 if not v1_signatures:
1713 raise exceptions.WebhookSignatureVerificationError(
1714 "No valid v1 signature found in the signature header. "
1715 "Expected format: 'v1,base64EncodedSignature'"
1716 )
1717
1718 # Construct the string to sign: webhookId.webhookTimestamp.payload
1719 to_sign = f"{webhook_id}.{webhook_timestamp}.{payload}"
1720
1721 # Compute expected signature
1722 expected_signature_bytes = hmac.new(
1723 key=secret.encode("utf-8"),
1724 msg=to_sign.encode("utf-8"),
1725 digestmod=hashlib.sha256,
1726 ).digest()
1727 expected_signature_b64 = base64.b64encode(expected_signature_bytes).decode(
1728 "utf-8"
1729 )
1730
1731 # Check if any of the provided signatures match (timing-safe)
1732 for provided_sig in v1_signatures:
1733 try:
1734 if hmac.compare_digest(provided_sig, expected_signature_b64):
1735 return # Signature is valid
1736 except Exception:
1737 continue # Invalid signature format, try next
1738
1739 raise exceptions.WebhookSignatureVerificationError(
1740 "The signature provided is invalid."
1741 )
1742
1743 def _validate_webhook_timestamp_header(
1744 self, timestamp: str, tolerance: int
1745 ) -> None:
1746 """
1747 Validate that the webhook timestamp header is within the allowed tolerance.
1748
1749 :param timestamp: The webhook timestamp from header (Unix seconds)
1750 :param tolerance: Maximum allowed age in seconds
1751 :raises WebhookSignatureVerificationError: If timestamp is outside tolerance
1752 :raises WebhookPayloadError: If timestamp format is invalid
1753 """
1754 try:
1755 timestamp_seconds = int(timestamp)
1756 except (ValueError, TypeError) as e:
1757 raise exceptions.WebhookPayloadError(
1758 f"Invalid webhook timestamp: {timestamp}. "
1759 "Expected Unix timestamp in seconds."
1760 ) from e
1761
1762 current_time = int(time.time())
1763 time_difference = abs(current_time - timestamp_seconds)
1764
1765 if time_difference > tolerance:
1766 raise exceptions.WebhookSignatureVerificationError(
1767 f"The webhook timestamp is outside the allowed tolerance. "
1768 f"The webhook was sent {time_difference} seconds ago, "
1769 f"but the maximum allowed age is {tolerance} seconds."
1770 )
1771
1772 def _parse_webhook_payload(
1773 self, payload: str
1774 ) -> t.Tuple[WebhookVersion, WebhookPayload, TriggerEvent]:
1775 """
1776 Parse webhook payload and detect version.
1777
1778 :param payload: The raw webhook payload string
1779 :return: Tuple of (version, raw_payload, normalized_payload)
1780 :raises WebhookPayloadError: If payload cannot be parsed
1781 """
1782 try:
1783 data = json.loads(payload)
1784 except json.JSONDecodeError as e:
1785 raise exceptions.WebhookPayloadError(
1786 f"Failed to parse webhook payload as JSON: {e}"
1787 ) from e
1788
1789 # Try V3 first — same envelope the realtime channel uses, so reuse the
1790 # shared detector/normalizer to keep the two paths from drifting.
1791 if _is_v3_envelope(data):
1792 return (
1793 WebhookVersion.V3,
1794 t.cast(WebhookPayloadV3, data),
1795 _build_trigger_event_from_v3(t.cast(WebhookPayloadV3, data)),
1796 )
1797
1798 # Try V2 (has 'type', 'timestamp', 'data' with nested fields)
1799 if (
1800 isinstance(data, dict)
1801 and "type" in data
1802 and "timestamp" in data
1803 and "data" in data
1804 and isinstance(data.get("data"), dict)
1805 and "connection_id" in data.get("data", {})
1806 ):
1807 return (
1808 WebhookVersion.V2,
1809 t.cast(WebhookPayloadV2, data),
1810 self._normalize_v2_payload(t.cast(WebhookPayloadV2, data)),
1811 )
1812
1813 # Try V1 (has 'trigger_name', 'connection_id', 'trigger_id', 'payload')
1814 if (
1815 isinstance(data, dict)
1816 and "trigger_name" in data
1817 and "connection_id" in data
1818 and "trigger_id" in data
1819 and "payload" in data
1820 ):
1821 return (
1822 WebhookVersion.V1,
1823 t.cast(WebhookPayloadV1, data),
1824 self._normalize_v1_payload(t.cast(WebhookPayloadV1, data)),
1825 )
1826
1827 raise exceptions.WebhookPayloadError(
1828 "Webhook payload does not match any known version (V1, V2, or V3). "
1829 "Please ensure the payload structure is correct."
1830 )
1831
1832 def _normalize_v1_payload(self, data: WebhookPayloadV1) -> TriggerEvent:
1833 """Normalize V1 payload to TriggerEvent format."""
1834 return t.cast(
1835 TriggerEvent,
1836 {
1837 "id": data["trigger_id"],
1838 "uuid": data["trigger_id"],
1839 "user_id": "", # V1 doesn't have user_id
1840 "toolkit_slug": "", # V1 doesn't have toolkit_slug
1841 "trigger_slug": data["trigger_name"],
1842 "metadata": {
1843 "id": data["trigger_id"],
1844 "uuid": data["trigger_id"],
1845 "toolkit_slug": "",
1846 "trigger_slug": data["trigger_name"],
1847 "trigger_data": None,
1848 "trigger_config": {},
1849 "connected_account": {
1850 "id": data["connection_id"],
1851 "uuid": data["connection_id"],
1852 "auth_config_id": "",
1853 "auth_config_uuid": "",
1854 "user_id": "",
1855 "status": "ACTIVE",
1856 },
1857 },
1858 "payload": data["payload"],
1859 "original_payload": None,
1860 },
1861 )
1862
1863 def _normalize_v2_payload(self, data: WebhookPayloadV2) -> TriggerEvent:
1864 """Normalize V2 payload to TriggerEvent format."""
1865 payload_data = data["data"]
1866 return t.cast(
1867 TriggerEvent,
1868 {
1869 "id": payload_data.get(
1870 "trigger_nano_id", payload_data.get("trigger_id", "")
1871 ),
1872 "uuid": payload_data.get("trigger_id", ""),
1873 "user_id": payload_data.get("user_id", ""),
1874 "toolkit_slug": data["type"].upper() if data.get("type") else "",
1875 "trigger_slug": data["type"].upper() if data.get("type") else "",
1876 "metadata": {
1877 "id": payload_data.get("trigger_nano_id", ""),
1878 "uuid": payload_data.get("trigger_id", ""),
1879 "toolkit_slug": data["type"].upper() if data.get("type") else "",
1880 "trigger_slug": data["type"].upper() if data.get("type") else "",
1881 "trigger_data": None,
1882 "trigger_config": {},
1883 "connected_account": {
1884 "id": payload_data.get("connection_nano_id", ""),
1885 "uuid": payload_data.get("connection_id", ""),
1886 "auth_config_id": "",
1887 "auth_config_uuid": "",
1888 "user_id": payload_data.get("user_id", ""),
1889 "status": "ACTIVE",
1890 },
1891 },
1892 "payload": {
1893 k: v
1894 for k, v in payload_data.items()
1895 if k
1896 not in (
1897 "connection_id",
1898 "connection_nano_id",
1899 "trigger_nano_id",
1900 "trigger_id",
1901 "user_id",
1902 )
1903 },
1904 "original_payload": None,
1905 },
1906 )