Integrations

The integration connection layer ties a catalogue connector to an encrypted credential, a field mapping, a sync schedule, and a rolled-up health status. It lives under /v1/admin/integrations/connections (api/routes/integration_connections.py) and is real, enforced code — not a mock surface.

Admin only

Every connection route requires the admin module and an admin/owner role. A connection id is always resolved within the caller's tenant_id, so a leaked id can't be read or mutated cross-tenant.

What a connection manages

GET /connections — every connection for the tenant plus a health_rollup for the manager header.
POST /connections — connect (or reconnect) a connector. Secrets go into the encrypted credential store under the connector's credential kind, the kind's test-connection verifier runs immediately, and the connection status reflects the result (connected, configuring, or error).
PATCH /connections/{id}/mapping and /schedule — bidirectional field mapping and sync cadence.
POST /connections/{id}/test — re-run the verifier and flip status.
DELETE /connections/{id} — disconnect.

Credential storage reuses the existing encrypted credential store and its per-kind verifier — this module never re-implements encryption or secret handling.

"Sync now" is deliberately honest

POST /connections/{id}/sync does not fabricate work that didn't happen:

live connectors are synced by their own dedicated scheduled engine. The button does not run that backfill synchronously and there's no off-cycle trigger wired up yet, so it records an audit-trail entry (integration_connection.sync_now_scheduled) and tells you the next scheduled run will pick up changes — rather than writing a phantom success run with zero records.
Every other connector records an honest unsupported sync run: credentials and mapping are saved, but an automated sync adapter for that vendor isn't built yet.

config_only means credentials, not sync

A config_only connector stores credentials and field mapping and validates the connection, but does not yet run an automated data sync. Treat those connectors as "wired and validated, automated sync on the roadmap."

Which connectors sync live

The catalogue (core/integrations/registry.py) marks each connector's sync_status:

live — Salesforce (market-leading-crm), Stripe, and the Google and Microsoft 365 calendars run real, scheduled two-way syncs.
config_only — a pipeline-first CRM connector, the generic sales-engagement and marketing-automation connectors, and the video/meeting connectors (Zoom, Microsoft Teams, Google Meet, Webex) store credentials and mapping but don't yet sync automatically.

Custom inbound webhook connector

The custom connector receives events at POST /v1/webhooks/custom/{tenant_id} (api/routes/custom_webhook.py). It verifies an X-Signature header — HMAC-SHA256 over the raw body, accepted as sha256=<hex> or bare hex, compared in constant time — against the per-tenant signing_secret stored on the custom_webhook credential. Verified deliveries record an inbound sync run on the connection so they show up in the health badge and audit trail.

Connect your CRMWalkthrough for the live Salesforce connector.Inbound webhooksDesign of the custom inbound receiver.WebhooksOutbound event subscriptions.Warehouse syncPush Pact data into your warehouse.