Skip to main content
Builder Imports with the App Store modal open
Imports extend a Builder workspace with reusable apps, connectors, MCP servers, custom code, and automation instructions. Use them when a page or automation needs to call an external system, reuse packaged logic, or expose a tool to agents. In a Builder workspace, the sidebar entry is named Imports. Use the add control beside it to open the App Store, where you choose the package to add to the workspace.

Import Fundamentals

Builder supports several import types:
  • API Integrations: Connect to external services via REST, GraphQL, or other API protocols
  • Database Connections: Access and manipulate data in various database systems
  • Webhook Mechanisms: Receive and send event notifications to external systems
  • File System Operations: Read, write, and process files in various formats
  • Authentication Systems: Connect with identity providers and SSO solutions
  • App Store Packages: Pre-built imports installed from the App Store
Each type serves different integration needs and scenarios.

API Integrations

1

HTTP Connections

Connect to external APIs using HTTP requests.HTTP integration supports:
  • Methods: GET, POST, PUT, DELETE, PATCH
  • Headers: Custom headers for authentication and metadata
  • Query Parameters: URL parameters for request configuration
  • Request Bodies: JSON, XML, form data, and other formats
  • Response Handling: Processing various response formats and status codes
HTTP is the foundation for most modern API integrations.
2

Authentication Setup

Configure secure authentication for API access.Authentication methods include:
  • API Keys: Simple key-based authentication
  • OAuth 2.0: Token-based authentication flow
  • Basic Auth: Username/password authentication
  • JWT: JSON Web Token authentication
  • Custom Schemes: Specialized authentication mechanisms
Proper authentication ensures secure access to protected resources.
3

Data Transformation

Process data between your application and external APIs. Transformation capabilities include:
  • Format Conversion: Between JSON, XML, CSV, and other formats
  • Field Mapping: Align field names and structures
  • Data Filtering: Include only relevant information
  • Aggregation: Combine data from multiple sources
  • Normalization: Standardize data formats and values
Transformation ensures compatibility between systems with different data models.
4

Error Handling

Implement robust error management strategies. Error handling approaches:
  • Status Code Handling: Respond to different HTTP status codes
  • Retry Logic: Attempt failed requests again
  • Fallback Strategies: Alternative approaches when integrations fail
  • Error Logging: Record detailed error information
  • User Feedback: Provide appropriate information to users
Effective error handling creates resilient integrations that gracefully handle failures.

Database Integrations

Connect to various database systems to work with structured data:
Connect to SQL databases such as:
  • MySQL
  • PostgreSQL
  • SQL Server
  • Oracle
  • SQLite
  • Connection Methods — Database drivers, connection pools, connection strings. Ensures optimal performance and resource utilization
  • Operations — SQL queries, stored procedures, transactions. Full support for database operations
  • Security — Encrypted connections, parameterized queries, least privilege. Protects against SQL injection and unauthorized access Example configuration for a PostgreSQL connection:
    connection:
      type: postgresql
      host: database.example.com
      port: 5432
      database: customer_data
      username: "{{secrets.DB_USERNAME}}"
      password: "{{secrets.DB_PASSWORD}}"
      ssl: true
      pool:
        min: 5
        max: 20
    

Webhook Integrations

Implement event-driven integrations with external systems:
Receive events and notifications from external systems:
  • Endpoint Creation: Generate unique webhook URLs
  • Authentication: Verify webhook sources
  • Payload Processing: Parse and validate incoming data
  • Event Routing: Direct webhooks to appropriate handlers
  • Response Generation: Acknowledge receipt with appropriate responses
  • URL Pattern — /api/[workspace-slug]/[automation-slug]. Each automation can serve as a webhook endpoint
  • Verification Methods — HMAC signatures, shared secrets, IP filtering. Ensures webhooks come from authorized sources
  • Processing Patterns — Synchronous (immediate response) or asynchronous (queued). Flexibility for different processing needs Example automation for receiving GitHub webhooks:
    [Trigger: API (webhook)]
    
    [Verify Signature: github-signature header]
    
    [Condition: Valid signature?]
    ├─ [Yes] → [Parse webhook payload]
    │           ↓
    │           [Switch: Based on event type]
    │           ├─ [push] → [Process code push]
    │           ├─ [issue] → [Process issue update]
    │           └─ [release] → [Process release]
    
    └─ [No] → [Log security warning]
    
               [Return 401 Unauthorized]
    
Send events and notifications to external systems:
  • Destination Configuration: Configure target URLs
  • Payload Formatting: Structure event data appropriately
  • Authentication: Add necessary authentication
  • Delivery Confirmation: Verify successful delivery
  • Retry Management: Handle delivery failures
  • Trigger Events — User actions, system events, scheduled processes. Various sources can trigger outbound webhooks
  • Authentication Methods — Headers, query parameters, payload signatures. Authenticate with receiving systems
  • Delivery Options — Synchronous (wait for response) or asynchronous (fire and forget). Fits different integration patterns Example automation for sending a Slack notification:
    [Trigger: New document created event]
    
    [Format Webhook Payload]
    
    [HTTP Request: POST to Slack webhook URL]
    
    [Condition: Successful delivery?]
    ├─ [Yes] → [Log successful notification]
    
    └─ [No] → [Retry logic]
    
               [If still failing after retries, log error]
    
Implement secure webhook patterns:
  • Signature Verification: Validate webhook authenticity
  • Payload Encryption: Protect sensitive data
  • Rate Limiting: Prevent abuse
  • IP Restrictions: Limit webhook sources
  • Payload Validation: Ensure data meets expectations
  • HMAC Signatures — SHA-256 or SHA-512 hash-based message authentication. Industry standard for webhook verification
  • Secrets Management — Secure storage and rotation of webhook secrets. Protects authentication credentials
  • Validation Patterns — Schema validation, data type checking, business rule enforcement. Ensures data integrity and security Example HMAC signature verification logic:
    const crypto = require('crypto');
    
    function verifyWebhook(payload, secret, signature) {
      const hmac = crypto.createHmac('sha256', secret);
      const computedSignature = hmac.update(payload).digest('hex');
      return crypto.timingSafeEqual(
        Buffer.from(computedSignature),
        Buffer.from(signature)
      );
    }
    

Authentication & Authorization

Secure your integrations with robust authentication and authorization:
Authenticate with external services:
  • API Keys: Simple key-based authentication
  • OAuth 2.0: Token-based authentication with various flows
    • Authorization Code
    • Client Credentials
    • Resource Owner Password
    • Implicit Flow
  • Bearer Tokens: Token-based authentication
  • Basic Authentication: Username/password encoded in headers
  • Custom Authentication: Specialized methods for specific services
  • Secret Storage — Secure storage of credentials. Uses workspace secrets for sensitive information
  • Token Management — Handling refresh tokens and expiration. Automatically refreshes expired tokens
  • Multi-step Flows — Support for complex authentication. Handles redirects and callbacks

File System Integrations

Work with files in various storage systems:
Access files within the workspace environment:
  • File Reading: Load file contents
  • File Writing: Create or update files
  • Directory Operations: List, create, delete directories
  • File Properties: Get metadata about files
  • Path Management: Work with file paths
  • Storage Location — Container filesystem or mounted volumes. Isolated storage per workspace
  • Access Control — Permission-based file access. Prevents unauthorized access
  • Operation Types — Synchronous and asynchronous file operations. Flexibility for different performance needs Example file reading operation:
    // Read a file asynchronously
    const content = await fs.readFile('/path/to/file.txt', 'utf8');
    console.log(content);
    
    // Write to a file
    await fs.writeFile('/path/to/output.txt', 'Hello, world!', 'utf8');
    
Connect to cloud-based storage services:
  • AWS S3: Amazon Simple Storage Service
  • Azure Blob Storage: Microsoft’s object storage
  • Google Cloud Storage: Google’s object storage
  • Dropbox: File hosting service
  • OneDrive/SharePoint: Microsoft’s document storage
  • Operations — Upload, download, list, delete. Complete file management
  • Authentication — Service-specific authentication methods. Secure access to cloud storage
  • Advanced Features — Presigned URLs, versioning, metadata. Specialized cloud capabilities Example S3 integration configuration:
    storage:
      type: s3
      region: us-west-2
      bucket: my-application-files
      accessKeyId: "{{secrets.AWS_ACCESS_KEY_ID}}"
      secretAccessKey: "{{secrets.AWS_SECRET_ACCESS_KEY}}"
      defaultACL: private
    
Process various document formats:
  • PDF: Parse and extract PDF content
  • Office Documents: Work with Word, Excel, PowerPoint
  • CSV/TSV: Process structured data files
  • JSON/XML: Parse and generate structured formats
  • Images: Process image files with OCR
  • Content Extraction — Text, tables, images, metadata. Comprehensive data extraction
  • Format Conversion — Between document formats. Transformation capabilities
  • Analysis — Structure recognition, classification, entity extraction. Document understanding Example document processing automation:
    [Trigger: File uploaded event]
    
    [Condition: File type?]
    ├─ [PDF] → [Extract text from PDF]
    ├─ [DOCX] → [Extract text from Word document]
    ├─ [XLSX] → [Extract tables from Excel]
    ├─ [Image] → [Perform OCR on image]
    └─ [Other] → [Return unsupported format error]
    
    [Process extracted content]
    
    [Store results]
    

Install Imports from the App Store

Accelerate integration with pre-built App Store packages:
Builder App Store modal for installing imports
1

Open Imports

In Builder, open the workspace and select Imports in the sidebar.
2

Browse the App Store

Click + next to Imports in the workspace sidebar. Builder opens the App Store modal directly.If you are already in the Imports pane, use Install App or Browse App Store to open the same modal.The App Store provides:
  • Categorized integration listings
  • Detailed descriptions and capabilities
  • Package tags such as MCP, production:app, or one-product
  • Documentation and examples
  • Version history and updates
3

Install an import

Add integrations to your workspace.The installation process:
  1. Select the desired package from the App Store
  2. Review permissions and capabilities
  3. Approve the installation
  4. Configure app-specific settings
  5. Set up authentication if required
4

Configure the import

Set up the integration for your specific needs. Configuration typically includes:
  • Connection settings (endpoints, hosts)
  • Authentication credentials
  • Default behavior options
  • Logging and monitoring preferences
  • Feature toggles and limitations
5

Use the imported capabilities

Leverage the integrated functionality in your workspace. Imports can provide:
  • React components or SDK helpers for UI integration
  • Automation instructions for backend integration
  • Events for integration state changes
  • Documentation on usage patterns
  • Examples for common scenarios

Productivity & Collaboration

Connect with common workplace tools:
    Microsoft 365 (Outlook, Teams, SharePoint)Google Workspace (Gmail, Drive, Calendar)SlackZoomTrello, Asana, Monday.com

CRM & Sales

Integrate with customer relationship platforms:
    SalesforceHubSpotDynamics 365ZendeskPipedrive

Data & Analytics

Connect to data platforms and analytics tools:
    SnowflakeDatabricksPower BITableauLooker

Enterprise Systems

Integrate with core business systems:
    SAPOracle ERPServiceNowWorkdayNetSuite

Developer Tools

Connect with development and DevOps platforms:
    GitHubGitLabJiraAzure DevOpsBitbucket

AI & Machine Learning

Integrate with AI and ML services:
    OpenAIAzure Cognitive ServicesGoogle Vertex AIHugging FaceAWS AI Services

Creating Custom Integrations

For specialized requirements, develop your own integrations:
Create integrations using existing automation capabilities:
  • Combine HTTP requests with data transformations
  • Set up authentication flows
  • Implement error handling and retries
  • Create event-based integration patterns
  • Build data synchronization processes
This approach requires no coding but may be limited for complex scenarios.

Integration Best Practices

Security First

Prioritize security in all integrations:
    Use secure authentication methodsStore credentials in workspace secretsImplement the principle of least privilegeValidate and sanitize all inputsEncrypt sensitive data in transit and at rest

Error Resilience

Build robust error handling:
    Implement appropriate retry strategiesCreate circuit breakers for failing servicesLog detailed error informationProvide meaningful error messagesHave fallback options for critical paths

Performance Optimization

Ensure efficient integration operations:
    Use connection pooling for databasesImplement caching where appropriateProcess large datasets in batchesUse asynchronous operations when possibleMonitor and optimize slow integrations

Monitoring & Logging

Maintain visibility into integration health:
    Log key integration eventsTrack performance metricsSet up alerts for integration failuresMonitor usage patterns and quotasImplement audit trails for sensitive operations

Versioning Strategy

Manage integration changes safely:
    Plan for API version changesTest integrations before upgradingMaintain backward compatibilityDocument integration requirementsImplement graceful degradation

Data Governance

Respect data policies and regulations:
    Understand data residency requirementsImplement data minimization principlesFollow retention policiesHandle PII according to regulationsDocument data flows for compliance

Integration Troubleshooting

Common authentication problems and solutions:
  • Invalid Credentials: Verify API keys, tokens, and usernames/passwords
  • Expired Tokens: Implement token refresh logic
  • Missing Scopes: Ensure OAuth scopes include required permissions
  • Certificate Issues: Check SSL/TLS certificate validity
  • Clock Skew: Synchronize system times for timestamp-based auth
Debugging approach:
  1. Check logs for specific authentication errors
  2. Verify credentials in workspace secrets
  3. Test authentication in a standalone tool (e.g., Postman)
  4. Review token lifecycle and expiration
  5. Check for recent API or authentication changes
Resolving connection issues:
  • Timeouts: Adjust timeout settings or optimize performance
  • Network Errors: Verify network connectivity and DNS resolution
  • Firewall Rules: Check if firewalls are blocking connections
  • Rate Limiting: Implement backoff strategies for rate limits
  • Service Unavailability: Monitor external service status
Debugging approach:
  1. Check network connectivity from your environment
  2. Verify endpoint URLs and port numbers
  3. Test with simpler requests to isolate issues
  4. Implement proper connection handling with retries
  5. Use monitoring tools to track connection patterns
Solving data formatting problems:
  • Schema Mismatches: Align data structures between systems
  • Encoding Issues: Ensure proper character encoding (UTF-8)
  • Type Conversions: Handle data type differences appropriately
  • Missing Fields: Add required fields or provide defaults
  • Format Validation: Validate data meets receiving system requirements
Debugging approach:
  1. Log actual data being sent and received
  2. Compare with API documentation requirements
  3. Implement data validation before sending
  4. Use transformation steps to correct format issues
  5. Test with sample data that is known to work
Addressing integration performance problems:
  • Slow Responses: Optimize request patterns or implement caching
  • High Latency: Look for network issues or service problems
  • Resource Constraints: Check for memory or CPU limitations
  • Concurrency Issues: Adjust parallel processing settings
  • Bottlenecks: Identify and optimize slowest components
Debugging approach:
  1. Measure performance at different steps
  2. Identify patterns (time of day, data size, etc.)
  3. Implement caching for frequently accessed data
  4. Optimize data transfer size and frequency
  5. Consider asynchronous processing for long-running operations
Troubleshooting webhook integration issues:
  • Delivery Failures: Check endpoint availability and response codes
  • Signature Validation: Verify HMAC signatures match
  • Payload Processing: Ensure webhook data is properly parsed
  • Event Triggers: Confirm events are triggering webhook calls
  • Rate Issues: Handle high-volume webhook scenarios
Debugging approach:
  1. Enable webhook logging on both sides
  2. Verify webhook URLs are correct and accessible
  3. Check authentication and signature validation
  4. Test with simplified payloads
  5. Monitor webhook delivery attempts and failures
Leveraging the Activity log for integration diagnostics:
  • Event Filtering: Focus on relevant integration events
  • Payload Inspection: View actual data sent and received
  • Error Analysis: Identify specific error conditions
  • Timeline Correlation: Connect related events
  • Pattern Recognition: Identify recurring issues
Debugging approach:
  1. Filter Activity log to relevant time period and event types
  2. Examine event sequences leading to failures
  3. Look for patterns in successful vs. failed interactions
  4. Analyze error details and contextual information
  5. Use real-time monitoring for immediate issue detection

Knowledges Webhook Integration

Implementing advanced integrations with Knowledges requires Builder and subscription to specific webhook events. This advanced functionality enables custom RAG pipelines and sophisticated AI agent behaviors.
Builder enables powerful integration with Knowledges through webhooks:
Subscribe to document events to enhance the knowledge base:
  • documents_created: Triggered when new documents are added
  • documents_updated: Triggered when documents are modified
  • documents_deleted: Triggered when documents are removed
Example use cases:
  • Custom document processing pipelines
  • Content enrichment with additional metadata
  • Advanced document validation
  • Integration with document management systems

Next Steps

Automations

Learn more about the backend processes that power integrations

Testing & Debugging

Explore how to troubleshoot and validate your integrations

RBAC

Understand how to secure access to integrations

Use Cases

See examples of integrations in real-world applications