Skip to content

Common Integration Patterns

This document describes proven patterns for building reliable integrations with WhiteLabelCRO.

Find or Create Pattern

Problem: Avoid duplicate records when syncing from external systems.

Solution: Search first, create only if not found.

How it works:

  1. Search for record by email or external_id
  2. If found: Use existing record (update if needed)
  3. If not found: Create new record

Use cases: - Lead capture from multiple sources (forms, ads, referrals) - Syncing contacts from external CRM - Inbound API integrations

Implementation: - Zapier: Use "Find or Create" action combination - n8n: IF node after search, route to create if empty - Make: Router with filters on search results - Custom: GET search endpoint, then conditionally POST

Key field: Use external_id to link records across systems reliably.

Event-Driven Sync

Problem: Keep external systems up-to-date in real-time.

Solution: Subscribe to relevant events and push updates downstream.

How it works:

  1. Subscribe to events via webhook
  2. When event occurs, push to external system
  3. Handle failures with retry logic

Use cases: - Update CRM when client status changes - Sync payments to accounting system - Send notifications on key events

Implementation: - Webhooks: Real-time push, minimal latency - Polling: Fallback option, use cursor-based pagination

Advantages: - Near real-time updates - Reduces API polling overhead - Scales to high event volumes

Considerations: - Requires publicly accessible endpoint - Must handle duplicate deliveries - Implement deduplication via event ID

Batch Import

Problem: Migrate or sync large datasets into WhiteLabelCRO.

Solution: Use write actions with rate limit awareness.

How it works:

  1. Read records from source system
  2. For each record, call create/update action
  3. Respect rate limits (100 writes/min)
  4. Use external_id for idempotency

Use cases: - Initial data migration from legacy CRM - Periodic bulk sync from external system - Importing leads from marketing campaigns

Implementation: - Batch records in groups of ~80-90 per minute - Add delays between batches if needed - Track failures for retry - Use external_id to prevent duplicates on retry

Best practices: - Run during off-peak hours if possible - Monitor rate limit headers - Implement exponential backoff on 429 errors

External ID Mapping

Problem: Link records across multiple systems reliably.

Solution: Use external_id field to store cross-system identifiers.

How it works:

  1. When creating records, include external_id (e.g., hubspot_12345)
  2. When searching, use external_id for guaranteed unique match
  3. When updating, find by external_id first

Use cases: - Bidirectional sync with HubSpot, Salesforce, etc. - Multi-system architectures - Deduplication across integrations

Format examples: - hubspot_123456 - salesforce_00Q1234567890 - form_response_abc123

Advantages: - Deterministic lookups - Survives email/phone changes - Enables safe retry operations

Idempotent Operations

Problem: Network failures or retries can cause duplicate records.

Solution: Use external_id or idempotency keys to make operations safe to retry.

How it works:

  1. Include external_id when creating records
  2. System checks if record with that external_id exists
  3. If exists: Update existing record
  4. If not: Create new record

Use cases: - Retry-safe API calls - Webhook processing with retries - Unreliable network conditions

Implementation: All write actions support external_id parameter. Always provide it when: - Creating leads from external forms - Syncing from other CRMs - Processing webhook deliveries

Key principle: Same request → same outcome (no side effects on retry).

Error Recovery

Problem: Integrations fail due to transient errors.

Solution: Implement smart retry logic and failure handling.

Retry strategy: - 429 Rate Limit: Wait Retry-After seconds, then retry - 503 System Contention: Wait 1-2 seconds, then retry - Network timeout: Retry with exponential backoff - 400 Bad Request: Don't retry, log for manual review - 401/403 Auth: Don't retry, fix credentials

Failure logging: - Store failed requests for manual review - Send alerts on repeated failures - Track failure patterns to identify root causes

Circuit breaker pattern: - After N consecutive failures, pause integration - Alert admin to investigate - Resume after issue resolved

Use cases: - Webhook delivery failures - Batch import resilience - Third-party API flakiness

Multi-System Fan-out

Problem: Single event needs to trigger multiple downstream actions.

Solution: Route events to multiple destinations.

How it works:

  1. Subscribe to event (e.g., payment.succeeded)
  2. Send notification to Slack
  3. Update accounting system
  4. Send receipt email to client

Implementation: - Zapier: Use Paths to route to multiple actions - n8n: Add multiple branches after webhook trigger - Make: Use Router to split scenario flow - Webhooks: Subscribe multiple endpoints to same event type

Use cases: - Payment succeeded → accounting + notification + receipt - Client created → CRM sync + welcome email + Slack alert - Agreement signed → document storage + notification + status update

Best practices: - Make each destination independent (one failure doesn't block others) - Use async processing to avoid timeout - Log delivery status per destination

Data Transformation

Problem: External systems expect different field formats or structures.

Solution: Map and transform data between systems.

Common transformations: - Name formatting: first_name + last_name → full_name - Date formats: ISO 8601 → localized format - Status mapping: WhiteLabelCRO status → external system status codes - Currency: Cents → dollars or other currencies

Implementation: - Zapier: Use Formatter steps - n8n: Use Set node or Code node - Make: Use Tools > Set variables - Custom: Middleware transformation layer

Use cases: - CRM field mapping - Accounting system sync - International integrations

Conditional Routing

Problem: Different event types or conditions require different handling.

Solution: Filter and route based on event content.

Routing criteria: - Event type: Route payment.succeeded vs payment.failed differently - Status: Only process clients in specific statuses - Amount: Flag high-value transactions - Fields present: Handle events with optional fields

Implementation: - Zapier: Use Filter and Paths - n8n: Use IF or Switch nodes - Make: Use Router with filters - Webhooks: Process conditionally in code

Use cases: - Failed payments → alert finance, succeeded → send receipt - High-value clients → notify sales team - Specific statuses → trigger stage-specific workflows

Best practices: - Keep routing logic simple and maintainable - Log which route was taken for debugging - Handle default/fallback cases

Webhook vs Polling Tradeoffs

Webhooks (Push)

Advantages: - Real-time delivery (seconds) - No polling overhead - Efficient for high-volume events

Disadvantages: - Requires public HTTPS endpoint - Must handle retries and duplicates - More complex security (signature verification)

Best for: - Real-time notifications - Event-driven workflows - Production integrations

Polling (Pull)

Advantages: - Simpler to implement - No public endpoint required - Full control over retrieval timing

Disadvantages: - Higher latency (polling interval) - More API calls (rate limit impact) - Cursor management required

Best for: - Development/testing - Internal tools - Low-frequency event processing

Hybrid approach: Use webhooks as primary delivery method, polling as fallback for missed events.

Audit Trail

Problem: Need to track all integration activity for compliance or debugging.

Solution: Log all events, API calls, and outcomes.

What to log: - Incoming events (type, ID, timestamp) - Outgoing API calls (endpoint, status, response time) - Errors and retries - User actions (who triggered what)

Storage: - External logging service (e.g., Datadog, Splunk) - Database table with structured logs - Cloud storage for long-term retention

Use cases: - Compliance requirements - Debugging integration issues - Performance monitoring - Security audits

Best practices: - Don't log sensitive data (SSN, passwords) - Include request IDs for correlation - Set retention policies - Make logs searchable