Skip to main content

SDK 0.6.0 Major Update: Cloudflare Workers Support and Breaking Changes

Version Information

TypeScript/JavaScript

  • Package: @composio/core and all provider packages
  • Version: 0.6.0+

Python

  • Package: composio and all provider packages
  • Version: 0.11.0+

This major release focuses on Cloudflare Workers compatibility, platform-specific optimizations, and critical bug fixes. It includes breaking changes in both TypeScript and Python SDKs.
Breaking Changes: This release includes breaking changes that require code modifications:TypeScript:
  1. Webhook verification: Now async + signature changed (must add await + new required params: id, timestamp)
  2. Mastra provider updated to v1 API
Python:
  1. Webhook verification: Signature changed (new required parameters: id, timestamp - still synchronous)
See the Migration Guide for detailed upgrade instructions.

Breaking Changes

1. Webhook Verification Breaking Changes

TypeScript PR: #2436 | Python PR: #2361 The webhook verification API has breaking changes in both SDKs to support multiple webhook versions (v1, v2, v3) and edge runtime compatibility.

TypeScript: Now Async + Signature Changed

The verifyWebhook() method has two breaking changes: it’s now async AND requires additional parameters. Before:
After:
Key Changes:
  • ⚠️ Now async - Must use await
  • ⚠️ New required parameter: id (from webhook-id header)
  • ⚠️ New required parameter: timestamp (from webhook-timestamp header)
  • ⚠️ Header name changed: x-composio-signature → webhook-signature
  • ⚠️ Return type changed: TriggerEvent → VerifyWebhookResult
Why?
  • Cloudflare Workers compatibility - uses Web Crypto API instead of node:crypto
  • Supports v1, v2, and v3 webhook formats with improved signature verification

Python: Signature Changed (v1/v2/v3 Support)

The method signature changed to support new webhook versions and requires additional headers. Before:
After:
Key Changes:
  • ✅ Still synchronous (no await needed)
  • ⚠️ New required parameter: id (webhook-id header)
  • ⚠️ New required parameter: timestamp (webhook-timestamp header)
  • ⚠️ Header name changed: x-composio-signature → webhook-signature
  • ⚠️ Return type changed: TriggerEvent → VerifyWebhookResult
  • ⚠️ All parameters now keyword-only (must use param=value)
Why? Supports v1, v2, and v3 webhook formats with improved signature verification.

2. Mastra v1 Provider Update

PR: #2433 The @composio/mastra provider has been updated to support Mastra v1, which has breaking API changes from v0.x.

Before (Mastra v0.x)

After (Mastra v1)

Changes Required

  1. Update Mastra dependency: npm install @mastra/core@latest
  2. Update provider initialization: Pass Mastra instance to provider
  3. Update tool handling: Mastra v1 uses different tool schema format
  4. Check Zod version: Mastra v1 supports both Zod v3 and v4
  5. Check Node.js version: Mastra v1 requires Node.js v22.13.0 or higher
We’ve added comprehensive E2E tests for both Zod v3 and v4 compatibility with Mastra v1 and Tool Router integration.

Major Features

3. Platform-Specific File Tool Modifier

PR: #2437 Separate implementations for Node.js and Cloudflare Workers to optimize file handling for each runtime. Key Improvements:
  • Node.js: Uses native file system APIs for better performance
  • Cloudflare Workers: Uses platform-specific APIs, avoids Node.js-only code
  • Automatic selection: SDK automatically picks the right implementation
  • No code changes needed: Works transparently
Related Change: This platform-agnostic approach is why composio.triggers.verifyWebhook() became async in Breaking Change #1. Node.js node:crypto is mostly synchronous, but the standard globalThis.crypto (Web Crypto API) available in Cloudflare Workers is async. To support both platforms with a single API, the method had to become async.

4. Platform-Specific Config Defaults

PR: #2437 Different default configurations for different runtimes to optimize behavior. Changed the autoUploadDownloadFiles default configuration for the Cloudflare Workers runtime, to avoid triggering runtime errors on unsupported features. Cloudflare Workers defaults:
Removed in a later release. The autoUploadDownloadFiles flag described above was removed in the v0.8.0 / Python v0.12.0 release train. Automatic file handling is now off by default on every runtime, and you opt in with dangerouslyAllowAutoUploadDownloadFiles instead. See SDKs remove legacy automatic file handling config for the full migration.
Benefits:
  • Zero config for common use cases
  • Optimized for each platform’s strengths
  • Override defaults when needed

5. Node Buffer → Uint8Array Refactoring

PR: #2438 All node:buffer usage replaced with standard Uint8Array for universal compatibility. Impact:
  • Works in Node.js and Cloudflare Workers
  • ESLint rules enforce this pattern going forward
  • Better type safety with standard types
  • Fully backward compatible - no code changes needed
Why This Matters: Removing Node.js-specific APIs like node:buffer and node:crypto enables Cloudflare Workers support. Cloudflare Workers don’t have access to Node.js built-in modules, so we use Web Standard APIs (Uint8Array, globalThis.crypto) that work in both Node.js and Cloudflare Workers.

Bug Fixes

6. Tool Fetching with Specific Version

PR: #2518 Fixed issues when executing tools with version constraints.

Before (Bug)

After (Fixed)

Test Coverage: Added 174 new test cases to prevent regression.

7. Python JSON Schema Default Values

PR: #2506 Fixed type coercion for stringified default values in JSON schemas.

Before (Bug)

After (Fixed)

Impact: Fixes runtime errors with tools that have stringified defaults in their schemas.

8. Salesforce Type Error Fix

PR: #2426 Fixed SALESFORCE_CREATE_LEAD type error with custom_fields parameter.

Before (Bug)

After (Fixed)

Technical Details: Implemented proper support for anyOf and allOf JSON Schema constructs in Python SDK.

Migration Guide

Step 1: Update Dependencies


Step 2: Update Webhook Verification (Required)

Update signature with new parameters and add await:
Express.js Example:
Cloudflare Workers Example:

Step 3: Update Mastra Integration (If Using)

Only required if you use @composio/mastra provider
Update your code:
Zod Compatibility: Mastra v1 works with both Zod v3 and v4. We test both versions in CI to ensure compatibility.

Step 4: Test Your Integration

  1. Run your test suite to catch any issues
  2. Test webhook verification if you use triggers
  3. Test file uploads/downloads - behavior improved but API unchanged
  4. Test in your target runtime (Node.js, Cloudflare Workers, etc.)

Backward Compatibility

Fully Compatible (No Changes Needed)

The following features work without any code changes:
  • ✅ All tool execution APIs
  • ✅ Connected accounts management
  • ✅ Authentication flows
  • ✅ Custom tools
  • ✅ Tool Router sessions
  • ✅ File upload/download (API unchanged, implementation improved)
  • ✅ All provider packages (except Mastra)
  • ✅ Python SDK usage (except webhook verification)

Requires Changes

The following features require code updates:
  • ⚠️ Webhook verification (TypeScript) - Must add await AND add id + timestamp parameters, update header names
  • ⚠️ Webhook verification (Python) - Must add id + timestamp parameters, update header names (still synchronous)
  • ⚠️ Mastra integration (TypeScript only) - Must update to v1 API

Impact Summary


Cloudflare Workers Support

This release adds support for Cloudflare Workers:
Key Features Working in Cloudflare Workers:
  • ✅ Tool execution
  • ✅ Connected accounts
  • ✅ Webhook verification
  • ✅ File upload/download
  • ✅ Custom tools

Testing

This release includes extensive E2E testing:
  • ✅ Node.js: Both CJS and ESM compatibility tests
  • ✅ Cloudflare Workers: Multiple test suites including Tool Router
  • ✅ Mastra v1: Tests for both Zod v3 and v4
  • ✅ File handling: Comprehensive tests for all platforms
  • ✅ Webhook verification: Tests for all supported runtimes
Total new tests: 200+ test cases added across TypeScript and Python SDKs.

Getting Help

If you encounter issues during migration:
  1. Check the docs: docs.composio.dev
  2. Join our Discord: discord.composio.dev
  3. Open an issue: github.com/ComposioHQ/composio/issues
  4. Email support: support@composio.dev

What’s Next

Future releases will focus on:
  • 🚀 Performance optimizations
  • 🔧 More platform-specific improvements
  • 📚 Enhanced TypeScript types
  • 🛠️ New tool integrations
  • 🔐 Advanced authentication flows
Stay tuned for updates!