Skip to content

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

feat(py): add tests for cross-sdk webhook handling parity between Python and TypeScriptSDK

jkomyno4ea885cd216a
diff --git a/python/tests/conftest.py b/python/tests/conftest.py
index 531e6b900..cca36bc31 100644
--- a/python/tests/conftest.py
+++ b/python/tests/conftest.py
@@ -1 +1,91 @@
"""pytest configuration module"""
+
+import base64
+import hashlib
+import hmac
+import json
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+from composio.core.models.triggers import Triggers
+
+
+def get_py_fixtures_dir() -> Path:
+ """Get the Python fixtures directory path."""
+ return Path(__file__).parent / "fixtures" / "webhook"
+
+
+def get_ts_fixtures_dir() -> Path:
+ """Get the TypeScript fixtures directory path."""
+ return (
+ Path(__file__).parent.parent.parent
+ / "ts"
+ / "packages"
+ / "core"
+ / "test"
+ / "fixtures"
+ / "webhook"
+ )
+
+
+def compute_signature(
+ webhook_id: str, timestamp: str, payload: str, secret: str
+) -> str:
+ """Compute webhook signature using HMAC-SHA256."""
+ to_sign = f"{webhook_id}.{timestamp}.{payload}"
+ signature = hmac.new(
+ key=secret.encode("utf-8"),
+ msg=to_sign.encode("utf-8"),
+ digestmod=hashlib.sha256,
+ ).digest()
+ return f"v1,{base64.b64encode(signature).decode('utf-8')}"
+
+
+def load_fixtures() -> list[dict]:
+ """Load all webhook fixtures from the fixtures directory."""
+ fixtures_dir = get_py_fixtures_dir()
+ fixtures = []
+ for fixture_file in fixtures_dir.glob("v*.json"):
+ if "golden" in fixture_file.name:
+ continue
+ with open(fixture_file) as f:
+ fixtures.append(json.load(f))
+ return fixtures
+
+
+def load_golden_signatures() -> dict:
+ """Load golden signatures for contract testing."""
+ fixtures_dir = get_py_fixtures_dir()
+ with open(fixtures_dir / "golden-signatures.json") as f:
+ return json.load(f)
+
+
+def mock_client() -> Mock:
+ """Create a mock HTTP client."""
+ client = Mock()
+ client.triggers_types = Mock()
+ client.trigger_instances = Mock()
+ client.trigger_instances.manage = Mock()
+ client.connected_accounts = Mock()
+ return client
+
+
+def triggers(mock_client: Mock) -> Triggers:
+ """Create a Triggers instance."""
+ return Triggers(client=mock_client)
+
+
+def webhook_fixtures() -> list[dict]:
+ """Load all webhook fixtures."""
+ return load_fixtures()
+
+
+def golden_signatures() -> dict:
+ """Load golden signatures."""
+ return load_golden_signatures()
diff --git a/python/tests/fixtures/webhook/golden-signatures.json b/python/tests/fixtures/webhook/golden-signatures.json
new file mode 100644
index 000000000..88e658d79
--- /dev/null
+++ b/python/tests/fixtures/webhook/golden-signatures.json
@@ -0,0 +1,47 @@
+{
+ "description": "Golden signature test cases - DO NOT MODIFY unless algorithm changes",
+ "algorithm": "HMAC-SHA256",
+ "format": "v1,base64(HMAC-SHA256(id.timestamp.payload, secret))",
+ "testCases": [
+ {
+ "name": "simple payload",
+ "id": "msg_test_001",
+ "timestamp": "1700000000",
+ "payload": "{\"test\":\"data\"}",
+ "secret": "test-secret",
+ "expectedSignature": "v1,4Fay6rvxXDEbH+4oA1fYP2BR/Bwzn3/7ONj40iJQagY="
+ },
+ {
+ "name": "unicode payload",
+ "id": "msg_test_002",
+ "timestamp": "1700000001",
+ "payload": "{\"message\":\"Hello World\"}",
+ "secret": "unicode-secret-key",
+ "expectedSignature": "v1,ICmAFUlesRqIFA44bU6Wlce5GszoHjG+w7nurcu5EWc="
+ },
+ {
+ "name": "complex nested payload",
+ "id": "msg_test_003",
+ "timestamp": "1700000002",
+ "payload": "{\"nested\":{\"array\":[1,2,3],\"object\":{\"key\":\"value\"}}}",
+ "secret": "complex-secret",
+ "expectedSignature": "v1,Vx/pw0yOiRRoxdfifaZ3zBKt4B3KkRKFVr6gLQNJs9Q="
+ },
+ {
+ "name": "empty data object",
+ "id": "msg_test_004",
+ "timestamp": "1700000003",
+ "payload": "{\"data\":{}}",
+ "secret": "empty-data-secret",
+ "expectedSignature": "v1,IbLtu+G65OH8Gw7ZFqy38ru+Jrg96yWfueYMMdaFYs0="
+ },
+ {
+ "name": "special characters in secret",
+ "id": "msg_test_005",
+ "timestamp": "1700000004",
+ "payload": "{\"test\":true}",
+ "secret": "secret!@#$%^&*()",
+ "expectedSignature": "v1,kUvMXJ0rouLoROxY70WIzV+zLQGpSRuCXv8evLTPjXg="
+ }
+ ]
+}
diff --git a/python/tests/fixtures/webhook/v1-github-push.json b/python/tests/fixtures/webhook/v1-github-push.json
new file mode 100644
index 000000000..1c2aab681
--- /dev/null
+++ b/python/tests/fixtures/webhook/v1-github-push.json
@@ -0,0 +1,16 @@
+{
+ "description": "V1 GitHub push webhook - legacy format sanitized",
+ "capturedAt": "2026-01-29T10:30:00Z",
+ "headers": {
+ "webhook-id": "msg_fixture_v1_001",
+ "webhook-timestamp": "1738150200",
+ "webhook-signature": "v1,A/VFbvOJ8JAzXZweWvc+IHaBie19NVKUpQKbeobt5xo="
+ },
+ "payload": "{\"trigger_name\":\"GITHUB_PUSH_EVENT\",\"connection_id\":\"conn_fixture_001\",\"trigger_id\":\"trigger_fixture_001\",\"payload\":{\"ref\":\"refs/heads/main\",\"commits\":[{\"id\":\"def456\",\"message\":\"Legacy commit\"}]},\"log_id\":\"log_fixture_003\"}",
+ "testSecret": "test-webhook-secret-for-fixtures",
+ "expectedResult": {
+ "version": "V1",
+ "triggerSlug": "GITHUB_PUSH_EVENT",
+ "triggerId": "trigger_fixture_001"
+ }
+}
diff --git a/python/tests/fixtures/webhook/v2-github-push.json b/python/tests/fixtures/webhook/v2-github-push.json
new file mode 100644
index 000000000..4384263cc
--- /dev/null
+++ b/python/tests/fixtures/webhook/v2-github-push.json
@@ -0,0 +1,16 @@
+{
+ "description": "V2 GitHub push webhook - sanitized real-world structure",
+ "capturedAt": "2026-01-29T10:30:00Z",
+ "headers": {
+ "webhook-id": "msg_fixture_v2_001",
+ "webhook-timestamp": "1738150200",
+ "webhook-signature": "v1,a/mTZohEnMvzupLGWsiDLhTctk+hgx3Q2r1ACjybkhk="
+ },
+ "payload": "{\"type\":\"github_push_event\",\"timestamp\":\"2026-01-29T10:30:00Z\",\"log_id\":\"log_fixture_002\",\"data\":{\"connection_id\":\"conn_uuid_fixture_002\",\"connection_nano_id\":\"ca_fixture_002\",\"trigger_nano_id\":\"ti_fixture_002\",\"trigger_id\":\"trigger_uuid_fixture_002\",\"user_id\":\"user_fixture_002\",\"ref\":\"refs/heads/main\",\"repository\":{\"name\":\"test-repo\"}}}",
+ "testSecret": "test-webhook-secret-for-fixtures",
+ "expectedResult": {
+ "version": "V2",
+ "triggerSlug": "GITHUB_PUSH_EVENT",
+ "userId": "user_fixture_002"
+ }
+}
diff --git a/python/tests/fixtures/webhook/v3-github-push.json b/python/tests/fixtures/webhook/v3-github-push.json
new file mode 100644
index 000000000..a9e3f15ab
--- /dev/null
+++ b/python/tests/fixtures/webhook/v3-github-push.json
@@ -0,0 +1,17 @@
+{
+ "description": "V3 GitHub push webhook - sanitized real-world structure",
+ "capturedAt": "2026-01-29T10:30:00Z",
+ "headers": {
+ "webhook-id": "msg_fixture_v3_001",
+ "webhook-timestamp": "1738150200",
+ "webhook-signature": "v1,GqTsMaDtroeNNR7rDDzEGVTtHfFtIDknXhmkCXss7cA="
+ },
+ "payload": "{\"id\":\"evt_fixture_v3_001\",\"timestamp\":\"2026-01-29T10:30:00Z\",\"type\":\"composio.trigger.message\",\"metadata\":{\"log_id\":\"log_fixture_001\",\"trigger_slug\":\"GITHUB_PUSH_EVENT\",\"trigger_id\":\"ti_fixture_001\",\"connected_account_id\":\"ca_fixture_001\",\"auth_config_id\":\"ac_fixture_001\",\"user_id\":\"user_fixture_001\"},\"data\":{\"ref\":\"refs/heads/main\",\"repository\":{\"name\":\"test-repo\",\"full_name\":\"user/test-repo\"},\"pusher\":{\"name\":\"test-user\"},\"commits\":[{\"id\":\"abc123\",\"message\":\"Test commit\"}]}}",
+ "testSecret": "test-webhook-secret-for-fixtures",
+ "expectedResult": {
+ "version": "V3",
+ "triggerSlug": "GITHUB_PUSH_EVENT",
+ "userId": "user_fixture_001",
+ "connectedAccountId": "ca_fixture_001"
+ }
+}
diff --git a/python/tests/test_cross_sdk_compatibility.py b/python/tests/test_cross_sdk_compatibility.py
new file mode 100644
index 000000000..83dcd0b60
--- /dev/null
+++ b/python/tests/test_cross_sdk_compatibility.py
@@ -0,0 +1,40 @@
+"""Cross-SDK compatibility tests.
+
+These tests verify that the Python SDK uses identical fixtures
+to the TypeScript SDK, ensuring webhook verification works consistently
+across both SDKs.
+"""
+
+import json
+
+import pytest
+
+from tests.conftest import get_py_fixtures_dir, get_ts_fixtures_dir
+
+
+class TestCrossSDKFixtureCompatibility:
+ """Tests verifying Python and TypeScript fixtures are synchronized."""
+
+ @pytest.mark.parametrize(
+ "fixture_name",
+ [
+ "golden-signatures.json",
+ "v1-github-push.json",
+ "v2-github-push.json",
+ "v3-github-push.json",
+ ],
+ )
+ def test_fixtures_are_identical(self, fixture_name: str) -> None:
+ """Verify TypeScript and Python fixtures are byte-identical."""
+ ts_path = get_ts_fixtures_dir() / fixture_name
+ py_path = get_py_fixtures_dir() / fixture_name
+
+ with open(ts_path) as f:
+ ts_content = json.load(f)
+ with open(py_path) as f:
+ py_content = json.load(f)
+
+ assert ts_content == py_content, (
+ f"Fixture {fixture_name} differs between TypeScript and Python SDKs. "
+ "Ensure fixtures are kept in sync."
+ )
diff --git a/python/tests/test_verify_webhook_integration.py b/python/tests/test_verify_webhook_integration.py
new file mode 100644
index 000000000..58b8ded7c
--- /dev/null
+++ b/python/tests/test_verify_webhook_integration.py
@@ -0,0 +1,311 @@
+"""Integration tests for verify_webhook using fixtures.
+
+These tests use the same fixtures as the TypeScript SDK to ensure
+cross-SDK compatibility and algorithm correctness.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+
+import pytest
+
+from composio import exceptions
+from composio.core.models.triggers import Triggers, WebhookVersion
+from tests.conftest import compute_signature, load_fixtures, load_golden_signatures
+
+
+class TestVerifyWebhook:
+ """Tests for webhook verification against fixture data."""
+
+ @pytest.mark.parametrize(
+ "fixture",
+ load_fixtures(),
+ ids=lambda f: f["description"],
+ )
+ def test_verify_fixture(self, triggers: Triggers, fixture: dict) -> None:
+ """Verify each fixture passes verification."""
+ result = triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=fixture["payload"],
+ signature=fixture["headers"]["webhook-signature"],
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+ assert result["version"].value == fixture["expectedResult"]["version"]
+ expected_slug = fixture["expectedResult"]["triggerSlug"]
+ assert result["payload"]["trigger_slug"] == expected_slug
+
+ if "userId" in fixture["expectedResult"]:
+ assert result["payload"]["user_id"] == fixture["expectedResult"]["userId"]
+
+ if "connectedAccountId" in fixture["expectedResult"]:
+ assert (
+ result["payload"]["metadata"]["connected_account"]["id"]
+ == fixture["expectedResult"]["connectedAccountId"]
+ )
+
+ if "triggerId" in fixture["expectedResult"]:
+ assert result["payload"]["id"] == fixture["expectedResult"]["triggerId"]
+
+ @pytest.mark.parametrize(
+ "version,expected_enum,expected_keys",
+ [
+ ("V3", WebhookVersion.V3, ["type", "metadata"]),
+ ("V2", WebhookVersion.V2, ["type", "data"]),
+ ("V1", WebhookVersion.V1, ["trigger_name", "connection_id"]),
+ ],
+ )
+ def test_detects_version(
+ self,
+ triggers: Triggers,
+ webhook_fixtures: list[dict],
+ version: str,
+ expected_enum: WebhookVersion,
+ expected_keys: list[str],
+ ) -> None:
+ """Test version detection for V1, V2, V3."""
+ fixture = next(
+ (f for f in webhook_fixtures if f["expectedResult"]["version"] == version),
+ None,
+ )
+ if fixture is None:
+ pytest.skip(f"No {version} fixture found")
+
+ result = triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=fixture["payload"],
+ signature=fixture["headers"]["webhook-signature"],
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+ assert result["version"] == expected_enum
+ for key in expected_keys:
+ assert key in result["raw_payload"]
+
+
+class TestGoldenSignatures:
+ """Contract tests for signature algorithm."""
+
+ @pytest.mark.parametrize(
+ "test_case",
+ load_golden_signatures()["testCases"],
+ ids=lambda tc: tc["name"],
+ )
+ def test_produces_identical_signature(self, test_case: dict) -> None:
+ """Verify signature algorithm produces identical output."""
+ computed = compute_signature(
+ test_case["id"],
+ test_case["timestamp"],
+ test_case["payload"],
+ test_case["secret"],
+ )
+ assert computed == test_case["expectedSignature"]
+
+ def test_algorithm_matches_documented_format(self, golden_signatures: dict) -> None:
+ """Verify algorithm documentation."""
+ assert golden_signatures["algorithm"] == "HMAC-SHA256"
+ assert (
+ golden_signatures["format"]
+ == "v1,base64(HMAC-SHA256(id.timestamp.payload, secret))"
+ )
+
+
+class TestSignatureValidation:
+ """Tests for signature algorithm validation."""
+
+ def test_computes_signature_using_id_timestamp_payload_format(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify signature is computed using id.timestamp.payload format."""
+ fixture = webhook_fixtures[0]
+ expected_signature = compute_signature(
+ fixture["headers"]["webhook-id"],
+ fixture["headers"]["webhook-timestamp"],
+ fixture["payload"],
+ fixture["testSecret"],
+ )
+ assert expected_signature == fixture["headers"]["webhook-signature"]
+
+ def test_rejects_signature_computed_with_payload_only(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Reject signature computed with only payload (wrong format)."""
+ fixture = webhook_fixtures[0]
+ wrong_signature = "v1," + base64.b64encode(
+ hmac.new(
+ key=fixture["testSecret"].encode("utf-8"),
+ msg=fixture["payload"].encode("utf-8"),
+ digestmod=hashlib.sha256,
+ ).digest()
+ ).decode("utf-8")
+
+ with pytest.raises(exceptions.WebhookSignatureVerificationError):
+ triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=fixture["payload"],
+ signature=wrong_signature,
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+ def test_rejects_signature_missing_id(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Reject signature computed with timestamp.payload (missing id)."""
+ fixture = webhook_fixtures[0]
+ to_sign = f"{fixture['headers']['webhook-timestamp']}.{fixture['payload']}"
+ wrong_signature = "v1," + base64.b64encode(
+ hmac.new(
+ key=fixture["testSecret"].encode("utf-8"),
+ msg=to_sign.encode("utf-8"),
+ digestmod=hashlib.sha256,
+ ).digest()
+ ).decode("utf-8")
+
+ with pytest.raises(exceptions.WebhookSignatureVerificationError):
+ triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=fixture["payload"],
+ signature=wrong_signature,
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+
+class TestPayloadStructure:
+ """Tests for payload structure validation."""
+
+ def test_preserves_exact_json_structure(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify raw payload matches fixture exactly."""
+ v3_fixture = next(
+ (f for f in webhook_fixtures if f["expectedResult"]["version"] == "V3"),
+ None,
+ )
+ if v3_fixture is None:
+ pytest.skip("No V3 fixture found")
+
+ result = triggers.verify_webhook(
+ id=v3_fixture["headers"]["webhook-id"],
+ payload=v3_fixture["payload"],
+ signature=v3_fixture["headers"]["webhook-signature"],
+ timestamp=v3_fixture["headers"]["webhook-timestamp"],
+ secret=v3_fixture["testSecret"],
+ tolerance=0,
+ )
+
+ parsed_payload = json.loads(v3_fixture["payload"])
+ assert result["raw_payload"] == parsed_payload
+
+ def test_normalizes_v3_payload(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify V3 payload is normalized correctly."""
+ v3_fixture = next(
+ (f for f in webhook_fixtures if f["expectedResult"]["version"] == "V3"),
+ None,
+ )
+ if v3_fixture is None:
+ pytest.skip("No V3 fixture found")
+
+ result = triggers.verify_webhook(
+ id=v3_fixture["headers"]["webhook-id"],
+ payload=v3_fixture["payload"],
+ signature=v3_fixture["headers"]["webhook-signature"],
+ timestamp=v3_fixture["headers"]["webhook-timestamp"],
+ secret=v3_fixture["testSecret"],
+ tolerance=0,
+ )
+
+ payload = result["payload"]
+ assert "id" in payload
+ assert "uuid" in payload
+ assert "trigger_slug" in payload
+ assert "toolkit_slug" in payload
+ assert "user_id" in payload
+ assert "payload" in payload
+ assert "metadata" in payload
+ assert "connected_account" in payload["metadata"]
+
+
+class TestWhitespaceSensitivity:
+ """Tests for whitespace sensitivity in payload verification."""
+
+ def test_fails_verification_if_whitespace_changes(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify whitespace changes cause verification failure."""
+ fixture = webhook_fixtures[0]
+ modified_payload = fixture["payload"].replace("{", "{ ")
+
+ expected_errors = (
+ exceptions.WebhookSignatureVerificationError,
+ exceptions.WebhookPayloadError,
+ )
+ with pytest.raises(expected_errors):
+ triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=modified_payload,
+ signature=fixture["headers"]["webhook-signature"],
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+ def test_fails_verification_if_payload_reserialized(
+ self, triggers: Triggers, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify re-serialization may cause verification failure."""
+ fixture = webhook_fixtures[0]
+ reserialized = json.dumps(json.loads(fixture["payload"]))
+
+ # Only test if re-serialization actually changed the payload
+ if reserialized != fixture["payload"]:
+ expected_errors = (
+ exceptions.WebhookSignatureVerificationError,
+ exceptions.WebhookPayloadError,
+ )
+ with pytest.raises(expected_errors):
+ triggers.verify_webhook(
+ id=fixture["headers"]["webhook-id"],
+ payload=reserialized,
+ signature=fixture["headers"]["webhook-signature"],
+ timestamp=fixture["headers"]["webhook-timestamp"],
+ secret=fixture["testSecret"],
+ tolerance=0,
+ )
+
+
+class TestFixtureConsistency:
+ """Tests for fixture consistency."""
+
+ def test_all_fixtures_use_same_test_secret(
+ self, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify all fixtures use the same test secret."""
+ secrets = {f["testSecret"] for f in webhook_fixtures}
+ assert len(secrets) == 1
+ assert "test-webhook-secret-for-fixtures" in secrets
+
+ def test_all_fixtures_have_unique_webhook_ids(
+ self, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify all fixtures have unique webhook IDs."""
+ ids = [f["headers"]["webhook-id"] for f in webhook_fixtures]
+ assert len(set(ids)) == len(webhook_fixtures)
+
+ def test_fixtures_cover_all_supported_versions(
+ self, webhook_fixtures: list[dict]
+ ) -> None:
+ """Verify fixtures cover V1, V2, and V3."""
+ versions = {f["expectedResult"]["version"] for f in webhook_fixtures}
+ assert {"V1", "V2", "V3"} <= versions