External SaaS Integration Patterns¶

This document captures repeatable patterns for integrating with external SaaS systems (CRMs, ATS, marketing tools, etc.). It is written for architects and engineers building integrations with third-party SaaS platforms.

ConnectSoft systems often need to integrate with external SaaS platforms for business operations, marketing, sales, and analytics. These patterns provide reusable approaches for common integration scenarios.

Note

These patterns are designed to be reusable across different external SaaS systems. The Factory can generate integration code following these patterns, ensuring consistency and maintainability.

Common Integration Scenarios¶

Operational System → Marketing Stack¶

Example: Customer data from operational system flows to marketing platforms (Braze, Segment, HubSpot)

Use Cases: - User registration events → Marketing automation - Purchase events → Email campaigns - Feature usage → Behavioral targeting

ATS → CRM¶

Example: Candidate data from ATS flows to CRM system

Use Cases: - Candidate applications → CRM leads - Interview scheduling → CRM activities - Offer acceptance → CRM opportunities

Core App → Analytics¶

Example: Application events flow to analytics platforms

Use Cases: - User actions → Analytics dashboards - Business events → Business intelligence - Performance metrics → Monitoring tools

E-Commerce → Fulfillment¶

Example: Order data flows to fulfillment systems

Use Cases: - Order creation → Fulfillment system - Inventory updates → E-commerce platform - Shipping updates → Order tracking

Core Patterns¶

Pattern	When to Use	Pros	Cons
Polling ETL	Periodic data synchronization, large datasets	Simple, reliable, works with any API	Latency, resource intensive
Webhooks → Queue → Processor	Real-time events, external push	Low latency, efficient	Requires webhook infrastructure
Event-Driven Streaming	High throughput, real-time processing	Scalable, decoupled	Complex, requires event infrastructure
REST API Direct	Simple CRUD, synchronous operations	Simple, standard	Tight coupling, synchronous
Batch ETL	Large volumes, scheduled processing	Efficient for bulk data	Latency, scheduling complexity

Pattern 1: Polling ETL¶

When to Use: - Periodic data synchronization - Large datasets - Systems without webhook support - Compliance and audit requirements

Implementation: - Scheduled job polls source API - Fetches incremental changes - Transforms and normalizes data - Pushes to destination API

Example: Daily sync of customer data from operational system to CRM

Pattern 2: Webhooks → Queue → Processor¶

When to Use: - Real-time event processing - External systems can push events - Low latency requirements - Decoupled processing

Implementation: - External system calls webhook endpoint - Webhook validates and queues event - Background processor consumes queue - Processor transforms and sends to destination

Example: User registration webhook → Queue → Marketing platform API

flowchart LR
    A[External SaaS] -->|Webhook| B[Webhook Endpoint]
    B --> C[Validation]
    C --> D[Event Queue]
    D --> E[Processor]
    E --> F[Transform]
    F --> G[Destination API]

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style D fill:#e8f5e9
    style E fill:#fff4e1
    style G fill:#f3e5f5

Hold "Alt" / "Option" to enable pan & zoom

Pattern 3: Event-Driven Streaming¶

When to Use: - High throughput requirements - Real-time processing - Multiple consumers - Decoupled architecture

Implementation: - Source system emits events to event bus - Event bus distributes to consumers - Consumers process and forward to external APIs - Multiple consumers can process same event

Example: Domain events → Event bus → Multiple external integrations

Security and Auth Considerations¶

Authentication Methods¶

OAuth2/OpenID Connect - Preferred for user-delegated access
API Keys - Simple, but less secure (use for service-to-service)
Service Principals - Azure AD service principals for Azure services
Certificate-Based - Mutual TLS for high-security scenarios

Secret Management¶

Azure Key Vault - Store API keys and secrets
Environment Variables - For non-sensitive configuration
Managed Identities - For Azure service authentication
Never Hardcode - Never commit secrets to source control

See: Security & Compliance for security guidelines.

OAuth2/OIDC Integration¶

Use ConnectSoft's HTTP/OIDC library for OAuth2 integrations:

Authorization Code Flow - For user-delegated access
Client Credentials Flow - For service-to-service authentication
Token Refresh - Automatic token refresh
Token Caching - Efficient token management

See: Libraries Catalog for HTTP/OIDC library details.

Error Handling and Resilience¶

Retry Strategies¶

Exponential Backoff - Retry with increasing delays
Circuit Breaker - Stop retrying after failures
Dead Letter Queue - Store failed messages for manual review
Idempotency - Ensure operations can be safely retried

Idempotency¶

Idempotency Keys - Use unique keys for operations
Deduplication - Track processed events
Idempotent Operations - Design APIs to be idempotent

Dead Letter Queues¶

Failed Message Storage - Store failed messages
Manual Review - Review and reprocess failures
Alerting - Alert on DLQ messages
Retry Logic - Automatic retry with limits

Example Pattern: Operational System → Marketing Stack¶

Scenario¶

Customer registration events from operational system need to flow to marketing platforms (Braze, Segment, HubSpot).

Architecture¶

flowchart LR
    A[Operational System] -->|Domain Event| B[Event Bus]
    B --> C[Integration Service]
    C --> D[Transform & Normalize]
    D --> E[Braze API]
    D --> F[Segment API]
    D --> G[HubSpot API]

    H[Webhook] -->|External Events| C

    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#fff4e1
    style E fill:#f3e5f5
    style F fill:#f3e5f5
    style G fill:#f3e5f5