Transformations

Transformations are powerful JavaScript functions that modify webhook payloads in real-time as they flow through your Connections. They enable you to reshape, enrich, filter, and customize webhook data before it reaches its destination, all within a secure, sandboxed environment.

Overview

Transformations act as programmable middleware in your webhook pipeline. When a webhook arrives at your Connection, it can be processed by a transformation before being forwarded to its destination. This allows you to:

• Adapt webhook formats between incompatible services
• Enrich payloads with additional data or computed fields
• Filter or validate incoming webhooks based on custom logic
• Inject authentication headers or signatures
• Route webhooks to different destinations based on content
• Transform data structures to match destination requirements

How Transformations Work

Transformations are JavaScript functions that run in a secure, isolated sandbox. Each transformation:

1. Receives the incoming webhook request (headers, body, method, URL)
2. Processes the data using your custom JavaScript logic
3. Returns a modified request object
4. Forwards the transformed payload to the destination

The Transformation API

Every transformation must register a handler function using the addHandler API:

addHandler('transform', async (request, context) => {
  // Your transformation logic here
  return modifiedRequest;
});

The handler receives two parameters:

• request: The incoming webhook data

  • method: HTTP method (GET, POST, etc.)
  • url: Original request URL
  • headers: Request headers object
  • body: Request body (parsed JSON or string)

• context: Execution context and metadata

  • organizationId: Your organization identifier
  • secrets: Organization secrets (available via process.env)
  • Additional metadata about the execution environment

Security & Isolation

Transformations run in a completely isolated environment powered by isolated-vm, providing enterprise-grade security:

Sandbox Features

• Complete isolation: Each execution runs in a fresh, isolated context
• Memory limits: 128MB per execution (configurable)
• Timeout protection: 5-second maximum execution time
• No network access: Transformations cannot make external API calls
• No file system access: Cannot read or write files
• Controlled APIs: Only approved JavaScript APIs are available

Organization Secrets

Transformations can securely access your organization's secrets through process.env:

addHandler('transform', async (request, context) => {
  // Access secrets securely
  const apiKey = process.env.API_KEY;
  const secretToken = process.env.SECRET_TOKEN;
  
  // Use secrets in your transformation
  return {
    ...request,
    headers: {
      ...request.headers,
      'Authorization': `Bearer ${apiKey}`,
      'X-Secret-Token': secretToken
    }
  };
});

Secrets are:

• Encrypted at rest
• Isolated per organization
• Never logged or exposed
• Available only during execution
• Managed through the Secrets API

Performance Considerations

Transformations are designed for high performance with minimal latency:

Execution Limits

• Memory: 128MB per execution
• Timeout: 5 seconds maximum
• CPU: Shared compute resources
• Payload size: Subject to platform limits

Optimization Tips

1. Keep transformations simple: Complex logic increases latency
2. Avoid heavy computations: The 5-second timeout is strict
3. Return early: Exit as soon as processing is complete
4. Minimize memory usage: Large data structures consume memory quickly
5. Use efficient algorithms: Choose O(n) over O(n²) operations

Error Handling

Transformations include comprehensive error tracking:

Error Types

• Syntax errors: Invalid JavaScript code
• Runtime errors: Errors during execution
• Timeout errors: Execution exceeds 5 seconds
• Memory errors: Exceeds 128MB limit
• Validation errors: Missing handler or invalid return value

Error Recovery

When a transformation fails:

1. The error is logged with full details
2. The webhook can be configured to:
   • Continue with the original payload (bypass transformation)
   • Fail the entire delivery
   • Trigger a retry based on your retry configuration

Debugging

All transformation executions are logged, including:

• Input payload
• Output result
• Execution time
• Memory usage
• Error details (if any)
• Console output from your code

Access logs through:

• The Transformations API (/api/v1/transformations/:id/logs)
• The Dashboard UI (coming soon)
• Real-time monitoring during testing

Integration with Connections

Transformations seamlessly integrate into your Connection workflow:

1. Create a transformation using the API
2. Attach it to a Connection's destination
3. Process incoming webhooks automatically
4. Monitor execution through logs and metrics

Execution Flow

Incoming Webhook → Source → Transformation → Destination
                               ↓
                         Transformation Logs

Async Processing

Transformations are designed to minimize impact on webhook delivery:

• Synchronous execution: Transformation runs inline with delivery
• Asynchronous logging: Logs are written after delivery completes
• Non-blocking errors: Failed transformations don't block retries
• Performance metrics: Track transformation impact on latency

Available JavaScript APIs

The sandbox provides a limited but useful set of JavaScript capabilities:

Supported

• Core JavaScript (ES2020+)
• JSON.parse() / JSON.stringify()
• Array, Object, String, Number methods
• Promise and async/await
• Date and basic time operations
• Math functions
• console.log() for debugging
• Regular expressions

Not Available

• fetch() or any network APIs
• setTimeout() / setInterval()
• require() / import (no external modules)
• File system operations
• Process spawning
• Direct database access

Pricing & Limits

Transformations are available on Team and Enterprise plans:

Team Plan

• Unlimited transformations
• 128MB memory per execution
• 5-second timeout
• Basic metrics and logging

Enterprise Plan

• Everything in Team
• Configurable memory limits
• Extended timeout options
• Advanced monitoring
• Priority support
• Custom integration assistance

Next Steps

Ready to start transforming your webhooks?

1. Create your first transformation with our step-by-step guide
2. Explore examples for common use cases
3. Review best practices for production deployments
4. Check the API reference for detailed endpoints

Transformations unlock the full potential of webhook automation, letting you connect any service to any other service, regardless of their native compatibility.