Drivers

Drivers are software modules that implement provider-specific integration logic. Each driver encapsulates the authentication, data ingestion, and normalization requirements for a specific third-party platform (e.g., Shopify, Stripe, Hotmart).

Driver Responsibilities

Drivers abstract the complexity of heterogeneous third-party APIs by handling three core functions:

1. Authentication Management

OAuth Flow Orchestration: Manage authorization code exchange, token refresh, and scope validation
API Key Rotation: Handle credential lifecycle for key-based authentication
Signature Verification: Validate webhook signatures using provider-specific algorithms (HMAC, JWT)

2. Data Ingestion

Drivers support two ingestion strategies based on provider capabilities:

Strategy	Mechanism	Use Case
Webhook (Push)	Provider sends events to platform endpoints	Real-time event delivery (Stripe, Shopify)
Polling (Pull)	Driver queries provider API on schedule	Providers without webhook support

3. Payload Normalization

Transform provider-specific data structures into the platform’s standardized schema:

Field Mapping: Convert provider field names to canonical format
Type Coercion: Normalize dates, currencies, and enumerations
Data Enrichment: Fetch related entities via additional API calls when necessary

Relationship to Installations

[!IMPORTANT] Every Installation requires exactly one Driver. There are no “generic” installations.

When you create an Installation, you instantiate a specific Driver configured for that customer’s connection. The Driver determines:

Which authentication method to use
How to ingest data (webhook vs. polling)
How to transform payloads for that provider

Example: Creating a Shopify installation instantiates the shopify driver, which knows how to handle Shopify’s OAuth flow, webhook signature validation, and order payload structure.

Driver Configuration

Drivers expose configuration parameters through the Installation’s settings object:

{
  "installation_id": "inst_abc123",
  "driver_id": "shopify",
  "settings": {
    "poll_interval": 5,
    "webhook_topics": ["orders/create", "orders/updated"],
    "api_version": "2024-01"
  }
}

Refer to the Processing Engine documentation for available configuration parameters.