Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(triggers): handle V3 envelope in realtime subscribe path [SUP-392] (#3567)
Anshu Garg56e0d781f312
diff --git a/python/composio/core/models/triggers.py b/python/composio/core/models/triggers.pyindex 6f6c36539..a4b5364d3 100644--- a/python/composio/core/models/triggers.py+++ b/python/composio/core/models/triggers.py@@ -431,6 +431,131 @@ class TriggerEventFilters(te.TypedDict):TriggerCallback = t.Callable[[TriggerEvent], None]+# Realtime trigger frames can carry message bodies / PII, so the raw frame is+# never logged in full — only a bounded preview when it fails to parse.+_MAX_LOGGED_FRAME_CHARS = 512+++def _truncate_frame(event: str) -> str:+ """Return a bounded preview of a raw frame for safe logging."""+ if len(event) <= _MAX_LOGGED_FRAME_CHARS:+ return event+ return f"{event[:_MAX_LOGGED_FRAME_CHARS]}… ({len(event)} chars total)"+++def _coerce_str(value: t.Any) -> str:+ """Coerce a possibly-missing or non-string field to ``str``.++ Mirrors the TS SDK's ``toStringOrDefault`` so realtime/webhook frames that+ carry ``None`` or a non-string identity field don't later raise+ ``AttributeError`` on ``.lower()`` / ``.split()``. ``None`` maps to "".+ """+ return "" if value is None else str(value)+++def _is_v3_envelope(data: t.Any) -> bool:+ """Return ``True`` if ``data`` is a modern V3 envelope.++ V3 payloads carry a ``type`` starting with ``composio.`` and a ``metadata``+ object, alongside top-level ``id`` and ``data`` keys. The same envelope is+ delivered over both the webhook channel and the realtime (Pusher) channel,+ so this is used to route either source through the V3 normalizer.+ """+ if not isinstance(data, dict):+ return False+ event_type = data.get("type", "")+ return (+ isinstance(event_type, str)+ and event_type.startswith("composio.")+ and isinstance(data.get("metadata"), dict)+ and "id" in data+ and "data" in data+ )+++def _build_trigger_event_from_v3(data: WebhookPayloadV3) -> TriggerEvent:+ """Normalize a V3 envelope (webhook or realtime) into a ``TriggerEvent``.++ Trigger frames are identified by their envelope ``type``+ (``composio.trigger.message``), not by the presence of every metadata+ field. The trigger-specific metadata fields are then read best-effort and+ coerced to ``str`` so a frame that omits or mistypes one of them is still+ delivered rather than silently demoted to a non-trigger event or raising+ ``AttributeError`` on the toolkit-slug split.+ """+ metadata = data.get("metadata") or {}+ event_type = data.get("type", "")++ if event_type == "composio.trigger.message":+ trigger_id = _coerce_str(metadata.get("trigger_id"))+ trigger_slug = _coerce_str(metadata.get("trigger_slug"))+ user_id = _coerce_str(metadata.get("user_id"))+ connected_account_id = _coerce_str(metadata.get("connected_account_id"))+ auth_config_id = _coerce_str(metadata.get("auth_config_id"))+ toolkit_slug = (+ trigger_slug.split("_")[0].upper() if "_" in trigger_slug else "UNKNOWN"+ )+ return t.cast(+ TriggerEvent,+ {+ "id": trigger_id,+ "uuid": trigger_id,+ "user_id": user_id,+ "toolkit_slug": toolkit_slug,+ "trigger_slug": trigger_slug,+ "metadata": {+ "id": trigger_id,+ "uuid": trigger_id,+ "toolkit_slug": toolkit_slug,+ "trigger_slug": trigger_slug,+ "trigger_data": None,+ "trigger_config": {},+ "connected_account": {+ "id": connected_account_id,+ "uuid": connected_account_id,+ "auth_config_id": auth_config_id,+ "auth_config_uuid": auth_config_id,+ "user_id": user_id,+ "status": "ACTIVE",+ },+ },+ "payload": data.get("data", {}),+ "original_payload": None,+ },+ )++ # Non-trigger V3 event (e.g., connection expired)+ event_id = _coerce_str(data.get("id"))+ return t.cast(+ TriggerEvent,+ {+ "id": event_id,+ "uuid": event_id,+ "user_id": "",+ "toolkit_slug": "COMPOSIO",+ "trigger_slug": event_type,+ "metadata": {+ "id": event_id,+ "uuid": event_id,+ "toolkit_slug": "COMPOSIO",+ "trigger_slug": event_type,+ "trigger_data": None,+ "trigger_config": {},+ "connected_account": {+ "id": "",+ "uuid": "",+ "auth_config_id": "",+ "auth_config_uuid": "",+ "user_id": "",+ "status": "ACTIVE",+ },+ },+ "payload": data.get("data", {}),+ "original_payload": data,+ },+ )++class TriggerSubscription(Resource):"""Trigger subscription."""@@ -460,45 +585,70 @@ class TriggerSubscription(Resource):return _wrapdef _parse_payload(self, event: str) -> t.Optional[TriggerEvent]:- """Parse event payload."""+ """Parse a realtime event payload into a ``TriggerEvent``.++ The realtime (Pusher) channel delivers either the modern V3 envelope+ (for projects on webhook version V3) or the legacy envelope (for V1/V2+ projects). Both shapes are handled here. Any unrecognized or malformed+ frame is logged and skipped (returns ``None``) rather than raising, so a+ single bad frame cannot tear down the subscription.+ """try:- data = t.cast(_TriggerData, json.loads(event))+ data = json.loads(event)except Exception as e:self.logger.warning(f"Error decoding payload: {e}")return None- return t.cast(- TriggerEvent,- {- "id": data["metadata"]["nanoId"],- "uuid": data["metadata"]["id"],- "user_id": data["metadata"]["connection"]["clientUniqueUserId"],- "toolkit_slug": data["appName"],- "trigger_slug": data["metadata"]["triggerName"],- "metadata": {- "id": data["metadata"]["nanoId"],- "uuid": data["metadata"]["id"],- "toolkit_slug": data["appName"],- "trigger_slug": data["metadata"]["triggerName"],- "trigger_data": data["metadata"]["triggerData"],- "trigger_config": data["metadata"]["triggerConfig"],- "connected_account": {- "id": data["metadata"]["connection"]["connectedAccountNanoId"],- "uuid": data["metadata"]["connection"]["id"],- "auth_config_id": data["metadata"]["connection"][- "authConfigNanoId"- ],- "auth_config_uuid": data["metadata"]["connection"][- "integrationId"- ],- "user_id": data["metadata"]["connection"]["clientUniqueUserId"],- "status": data["metadata"]["connection"]["status"],+ try:+ # V3 envelope — same shape as the V3 webhook payload.+ if _is_v3_envelope(data):+ return _build_trigger_event_from_v3(t.cast(WebhookPayloadV3, data))++ # Legacy envelope (V1/V2 projects).+ legacy = t.cast(_TriggerData, data)+ return t.cast(+ TriggerEvent,+ {+ "id": legacy["metadata"]["nanoId"],+ "uuid": legacy["metadata"]["id"],+ "user_id": legacy["metadata"]["connection"]["clientUniqueUserId"],+ "toolkit_slug": legacy["appName"],+ "trigger_slug": legacy["metadata"]["triggerName"],+ "metadata": {+ "id": legacy["metadata"]["nanoId"],+ "uuid": legacy["metadata"]["id"],+ "toolkit_slug": legacy["appName"],+ "trigger_slug": legacy["metadata"]["triggerName"],+ "trigger_data": legacy["metadata"].get("triggerData"),+ "trigger_config": legacy["metadata"]["triggerConfig"],+ "connected_account": {+ "id": legacy["metadata"]["connection"][+ "connectedAccountNanoId"+ ],+ "uuid": legacy["metadata"]["connection"]["id"],+ "auth_config_id": legacy["metadata"]["connection"][+ "authConfigNanoId"+ ],+ "auth_config_uuid": legacy["metadata"]["connection"][+ "integrationId"+ ],+ "user_id": legacy["metadata"]["connection"][+ "clientUniqueUserId"+ ],+ "status": legacy["metadata"]["connection"]["status"],+ },},+ "payload": legacy.get("payload"),+ "original_payload": legacy.get("originalPayload"),},- "payload": data["payload"],- "original_payload": data["originalPayload"],- },- )+ )+ except Exception as e:+ # A single malformed frame must never propagate into pysher's+ # dispatch loop (which calls callbacks with no try/except) and tear+ # down the subscription, so catch broadly — AttributeError and+ # others, not just KeyError/TypeError — and skip the frame.+ self.logger.warning(f"Error parsing trigger payload: {e}")+ return Nonedef _handle_chunked_events(self, event: str) -> None:"""Handle chunked events."""@@ -528,7 +678,16 @@ class TriggerSubscription(Resource):)for name, check in checks:value = filters.get(name)- if value is None or str(value).lower() == check.lower():+ if value is None:+ # No filter set for this field — nothing to match against.+ continue++ # ``check`` is str()-wrapped because realtime frames may carry+ # non-string identity fields; an empty event-side value is treated+ # as a non-match so synthesized "" fields don't fail open into a+ # filter that happens to be "".+ check_str = str(check)+ if check_str and str(value).lower() == check_str.lower():continueself.logger.debug(@@ -561,7 +720,12 @@ class TriggerSubscription(Resource):"""Filter events and call the callback function."""data = self._parse_payload(event=event)if data is None:- self.logger.error(f"Error parsing trigger payload: {event}")+ # _parse_payload already logged the specific reason; here we only+ # note that the frame was skipped, with a bounded preview so a+ # PII-bearing frame isn't dumped in full.+ self.logger.error(+ f"Skipping unparseable trigger frame: {_truncate_frame(event)}"+ )returnself.logger.debug(@@ -1092,24 +1256,13 @@ class Triggers(Resource):f"Failed to parse webhook payload as JSON: {e}") from e- # Try V3 first (has 'type' starting with 'composio.' and 'metadata' as dict)- # Metadata shape varies by event type (trigger vs connection events),- # so we only check that it's a dict here.- v3_metadata = data.get("metadata") if isinstance(data, dict) else None- v3_metadata_valid = isinstance(v3_metadata, dict)- v3_type = data.get("type", "") if isinstance(data, dict) else ""- if (- isinstance(data, dict)- and isinstance(v3_type, str)- and v3_type.startswith("composio.")- and v3_metadata_valid- and "id" in data- and "data" in data- ):+ # Try V3 first — same envelope the realtime channel uses, so reuse the+ # shared detector/normalizer to keep the two paths from drifting.+ if _is_v3_envelope(data):return (WebhookVersion.V3,t.cast(WebhookPayloadV3, data),- self._normalize_v3_payload(t.cast(WebhookPayloadV3, data)),+ _build_trigger_event_from_v3(t.cast(WebhookPayloadV3, data)),)# Try V2 (has 'type', 'timestamp', 'data' with nested fields)@@ -1221,131 +1374,3 @@ class Triggers(Resource):"original_payload": None,},)-- def _normalize_v3_payload(self, data: WebhookPayloadV3) -> TriggerEvent:- """Normalize V3 payload to TriggerEvent format."""- metadata = data["metadata"]-- # Check if this is a trigger event (has trigger-specific metadata fields)- is_trigger_event = all(- k in metadata- for k in (- "trigger_id",- "trigger_slug",- "user_id",- "connected_account_id",- "auth_config_id",- "log_id",- )- )-- if is_trigger_event:- trigger_data = t.cast(WebhookTriggerPayloadV3, data)- trigger_metadata = trigger_data["metadata"]- return t.cast(- TriggerEvent,- {- "id": trigger_metadata["trigger_id"],- "uuid": trigger_metadata["trigger_id"],- "user_id": trigger_metadata["user_id"],- "toolkit_slug": trigger_metadata["trigger_slug"]- .split("_")[0]- .upper()- if "_" in trigger_metadata["trigger_slug"]- else "UNKNOWN",- "trigger_slug": trigger_metadata["trigger_slug"],- "metadata": {- "id": trigger_metadata["trigger_id"],- "uuid": trigger_metadata["trigger_id"],- "toolkit_slug": trigger_metadata["trigger_slug"]- .split("_")[0]- .upper()- if "_" in trigger_metadata["trigger_slug"]- else "UNKNOWN",- "trigger_slug": trigger_metadata["trigger_slug"],- "trigger_data": None,- "trigger_config": {},- "connected_account": {- "id": trigger_metadata["connected_account_id"],- "uuid": trigger_metadata["connected_account_id"],- "auth_config_id": trigger_metadata["auth_config_id"],- "auth_config_uuid": trigger_metadata["auth_config_id"],- "user_id": trigger_metadata["user_id"],- "status": "ACTIVE",- },- },- "payload": trigger_data["data"],- "original_payload": None,- },- )-- # Non-trigger V3 event (e.g., connection expired)- event_type = data.get("type", "")- return t.cast(- TriggerEvent,- {- "id": data.get("id", ""),- "uuid": data.get("id", ""),- "user_id": "",- "toolkit_slug": "COMPOSIO",- "trigger_slug": event_type,- "metadata": {- "id": data.get("id", ""),- "uuid": data.get("id", ""),- "toolkit_slug": "COMPOSIO",- "trigger_slug": event_type,- "trigger_data": None,- "trigger_config": {},- "connected_account": {- "id": "",- "uuid": "",- "auth_config_id": "",- "auth_config_uuid": "",- "user_id": "",- "status": "ACTIVE",- },- },- "payload": data.get("data", {}),- "original_payload": data,- },- )-- def _transform_trigger_data(self, data: _TriggerData) -> TriggerEvent:- """- Transform raw trigger data to TriggerEvent format.-- :param data: The raw trigger data- :return: The transformed TriggerEvent- """- return t.cast(- TriggerEvent,- {- "id": data["metadata"]["nanoId"],- "uuid": data["metadata"]["id"],- "user_id": data["metadata"]["connection"]["clientUniqueUserId"],- "toolkit_slug": data["appName"],- "trigger_slug": data["metadata"]["triggerName"],- "metadata": {- "id": data["metadata"]["nanoId"],- "uuid": data["metadata"]["id"],- "toolkit_slug": data["appName"],- "trigger_slug": data["metadata"]["triggerName"],- "trigger_data": data["metadata"].get("triggerData"),- "trigger_config": data["metadata"]["triggerConfig"],- "connected_account": {- "id": data["metadata"]["connection"]["connectedAccountNanoId"],- "uuid": data["metadata"]["connection"]["id"],- "auth_config_id": data["metadata"]["connection"][- "authConfigNanoId"- ],- "auth_config_uuid": data["metadata"]["connection"][- "integrationId"- ],- "user_id": data["metadata"]["connection"]["clientUniqueUserId"],- "status": data["metadata"]["connection"]["status"],- },- },- "payload": data.get("payload"),- "original_payload": data.get("originalPayload"),- },- )diff --git a/python/tests/test_triggers.py b/python/tests/test_triggers.pyindex d42c17770..dddddd1ae 100644--- a/python/tests/test_triggers.py+++ b/python/tests/test_triggers.py@@ -12,7 +12,13 @@ import pytestfrom composio_client import omitfrom composio import exceptions-from composio.core.models.triggers import Triggers, WebhookVersion+from composio.core.models.triggers import (+ _MAX_LOGGED_FRAME_CHARS,+ Triggers,+ TriggerSubscription,+ WebhookVersion,+ _truncate_frame,+)class TestTriggers:@@ -1124,3 +1130,255 @@ class TestVerifyWebhook:"""Test that WebhookPayloadError inherits from TriggerError."""error = exceptions.WebhookPayloadError("test")assert isinstance(error, exceptions.TriggerError)+++class TestTriggerSubscriptionParsing:+ """Tests for realtime (Pusher) payload parsing in TriggerSubscription."""++ @pytest.fixture+ def subscription(self):+ """Create a TriggerSubscription with a mock client."""+ return TriggerSubscription(client=Mock())++ def test_parse_payload_v3_realtime_envelope(self, subscription):+ """A V3 realtime envelope is parsed (no KeyError: 'nanoId')."""+ event = json.dumps(+ {+ "id": "evt-1",+ "type": "composio.trigger.message",+ "metadata": {+ "log_id": "log-1",+ "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",+ "trigger_id": "ti_abc",+ "connected_account_id": "ca_abc",+ "auth_config_id": "ac_abc",+ "user_id": "user-1",+ },+ "data": {"subject": "hello"},+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["id"] == "ti_abc"+ assert result["trigger_slug"] == "GMAIL_NEW_GMAIL_MESSAGE"+ assert result["toolkit_slug"] == "GMAIL"+ assert result["user_id"] == "user-1"+ assert result["payload"] == {"subject": "hello"}+ assert result["metadata"]["connected_account"]["id"] == "ca_abc"+ assert result["metadata"]["connected_account"]["auth_config_id"] == "ac_abc"++ def test_parse_payload_legacy_envelope(self, subscription):+ """A legacy (V1/V2) realtime envelope still parses correctly."""+ event = json.dumps(+ {+ "appName": "gmail",+ "payload": {"subject": "hello"},+ "originalPayload": {"raw": 1},+ "metadata": {+ "id": "uuid-1",+ "nanoId": "ti_abc",+ "triggerName": "GMAIL_NEW_GMAIL_MESSAGE",+ "triggerData": "",+ "triggerConfig": {},+ "connection": {+ "id": "conn-uuid",+ "connectedAccountNanoId": "ca_abc",+ "authConfigNanoId": "ac_abc",+ "integrationId": "int-uuid",+ "clientUniqueUserId": "user-1",+ "status": "ACTIVE",+ },+ },+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["id"] == "ti_abc"+ assert result["toolkit_slug"] == "gmail"+ assert result["trigger_slug"] == "GMAIL_NEW_GMAIL_MESSAGE"+ assert result["metadata"]["connected_account"]["id"] == "ca_abc"+ assert result["original_payload"] == {"raw": 1}++ def test_parse_payload_malformed_returns_none(self, subscription):+ """Truly undecodable or unrecognized frames are skipped, not raised."""+ assert subscription._parse_payload("not-json") is None+ assert subscription._parse_payload(json.dumps({"unexpected": True})) is None++ def test_parse_payload_legacy_non_dict_metadata_does_not_raise(self, subscription):+ """A legacy frame with a non-dict metadata is skipped, not raised.++ Guards the broadened `except Exception` in _parse_payload: such a frame+ must return None rather than propagate into pysher's dispatch loop.+ """+ event = json.dumps({"appName": "gmail", "metadata": "not-a-dict"})+ assert subscription._parse_payload(event) is None++ def test_parse_payload_non_trigger_v3_event(self, subscription):+ """A non-trigger composio.* event is normalized as a COMPOSIO event."""+ event = json.dumps(+ {+ "id": "evt-1",+ "type": "composio.connected_account.expired",+ "metadata": {"project_id": "pr_1"},+ "data": {"status": "EXPIRED"},+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["toolkit_slug"] == "COMPOSIO"+ assert result["trigger_slug"] == "composio.connected_account.expired"+ assert result["original_payload"] == json.loads(event)++ def test_parse_payload_trigger_empty_metadata_does_not_raise(self, subscription):+ """A trigger frame with empty metadata is delivered with empty identity."""+ event = json.dumps(+ {+ "id": "evt-1",+ "type": "composio.trigger.message",+ "metadata": {},+ "data": {},+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["trigger_slug"] == ""+ assert result["toolkit_slug"] == "UNKNOWN"++ def test_parse_payload_legacy_missing_optional_fields(self, subscription):+ """A legacy frame missing optional fields is delivered, not dropped."""+ event = json.dumps(+ {+ "appName": "gmail",+ "payload": {"subject": "hello"},+ # originalPayload + triggerData intentionally omitted+ "metadata": {+ "id": "uuid-1",+ "nanoId": "ti_abc",+ "triggerName": "GMAIL_NEW_GMAIL_MESSAGE",+ "triggerConfig": {},+ "connection": {+ "id": "conn-uuid",+ "connectedAccountNanoId": "ca_abc",+ "authConfigNanoId": "ac_abc",+ "integrationId": "int-uuid",+ "clientUniqueUserId": "user-1",+ "status": "ACTIVE",+ },+ },+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["original_payload"] is None+ assert result["metadata"]["trigger_data"] is None++ def test_parse_payload_trigger_keyed_off_type_not_all_metadata(self, subscription):+ """A trigger frame missing one metadata field is still a trigger event.++ Detection keys off ``type == "composio.trigger.message"`` rather than+ requiring all six metadata fields, so the event is delivered (not+ silently demoted to a non-trigger COMPOSIO event).+ """+ event = json.dumps(+ {+ "id": "evt-1",+ "type": "composio.trigger.message",+ "metadata": {+ # ``log_id`` intentionally omitted+ "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",+ "trigger_id": "ti_abc",+ "connected_account_id": "ca_abc",+ "auth_config_id": "ac_abc",+ "user_id": "user-1",+ },+ "data": {"subject": "hello"},+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["trigger_slug"] == "GMAIL_NEW_GMAIL_MESSAGE"+ assert result["toolkit_slug"] == "GMAIL"+ assert result["user_id"] == "user-1"++ def test_parse_payload_non_string_trigger_slug_does_not_raise(self, subscription):+ """A null/non-string trigger_slug must not raise AttributeError (Vector A)."""+ event = json.dumps(+ {+ "id": "evt-1",+ "type": "composio.trigger.message",+ "metadata": {+ "trigger_slug": None,+ "trigger_id": "ti_abc",+ "connected_account_id": "ca_abc",+ "auth_config_id": "ac_abc",+ "user_id": 123,+ "log_id": "log-1",+ },+ "data": {"subject": "hello"},+ }+ )++ result = subscription._parse_payload(event)++ assert result is not None+ assert result["trigger_slug"] == ""+ assert result["toolkit_slug"] == "UNKNOWN"+ assert result["user_id"] == "123"++ @staticmethod+ def _make_event(**overrides):+ """Build a minimal TriggerEvent dict for filter-matching tests."""+ event = {+ "id": "ti_1",+ "uuid": "ti_1",+ "user_id": "user-1",+ "toolkit_slug": "GMAIL",+ "trigger_slug": "GMAIL_NEW_GMAIL_MESSAGE",+ "metadata": {+ "id": "ti_1",+ "connected_account": {+ "id": "ca_1",+ "auth_config_id": "ac_1",+ },+ },+ }+ event.update(overrides)+ return event++ def test_filters_match_no_filters_matches(self, subscription):+ """An empty filterset matches any event."""+ assert subscription._filters_match(self._make_event(), {}, "cb") is True++ def test_filters_match_does_not_crash_on_non_string_event_value(self, subscription):+ """A non-string identity field must not raise AttributeError (Vector B)."""+ event = self._make_event(user_id=123)+ assert subscription._filters_match(event, {"user_id": "123"}, "cb") is True+ assert subscription._filters_match(event, {"user_id": "999"}, "cb") is False++ def test_filters_match_empty_event_value_does_not_fail_open(self, subscription):+ """A synthesized empty identity field must not match a "" filter."""+ event = self._make_event(user_id="")+ assert subscription._filters_match(event, {"user_id": ""}, "cb") is False++ def test_truncate_frame_bounds_long_frames(self):+ """A long raw frame is truncated so PII-bearing frames aren't dumped."""+ short = "x" * 10+ assert _truncate_frame(short) == short++ long = "y" * (_MAX_LOGGED_FRAME_CHARS + 100)+ truncated = _truncate_frame(long)+ assert len(truncated) < len(long)+ assert truncated.startswith("y" * _MAX_LOGGED_FRAME_CHARS)+ assert str(len(long)) in truncated