Connectors

Build third-party data integrations with defineConnector — streams, webhooks, and connection setup.

A connector is a special kind of extension whose primary job is pulling data from an external system (Stripe, Shopify, your bank’s API) and emitting it as canonical Backfill entities. Connectors share the file/folder conventions of plain extensions but use a different manifest entry point — defineConnector — and a connector-specific runtime helper, ingest.

Read in order:

1. Overview — when to use defineConnector vs defineExtension.
2. Streams — poll vs webhook modes, scheduling, checkpoints.
3. Webhooks — receiving events from the source system.
4. Connection setup — testConnection, setup instructions, webhook URL templates.
5. OAuth — host-managed authorization-code flows, runtime tokens, and OAuth test fixtures.
6. Settings schema — JSON-Schema-driven connection configuration with secret fields.
7. Sync routes — the src/api/sync/<stream>.ts contract and ingest.canonical.
8. Testing — local route tests with @backfill-io/sdk/testing.

• Overview

  When to reach for defineConnector and what it gives you over a plain extension.

• Streams

  Declare what your connector ingests. Each stream has a key and a mode (poll or webhook).

• Webhooks

  Declare a signed webhook endpoint and verify it in the route handler.

• Connection setup

  testConnection, setup instructions, and webhook URL templates — the install flow for a connector.

• OAuth

  Declare connector OAuth, use host-managed tokens at runtime, and test OAuth routes locally.

• Settings schema

  JSON Schema describing per-installation connection settings — including encrypted secret fields.

• Sync routes

  Per-stream poll handlers that fetch from the provider and emit canonical records.

• Testing

  Unit-test connector routes locally with the SDK testing runtime.