> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Integration

> Connect an API-key or webhook-secret integration

Connect an integration whose setup only needs an API key and/or a webhook signing secret: Polar, Paddle, Dodo Payments, Whop, Creem, Chargebee, Clerk, PostHog, or Affonso.

Credentials are validated against the provider where possible, stored encrypted, and never returned by any endpoint. Payment providers queue their initial revenue backfill automatically; Affonso queues its affiliate backfill; PostHog can optionally import its event history.

The response includes `webhookUrl` - configure it in the provider's webhook settings with the same secret you passed here, or live events will not arrive. Calling this for an already-connected provider replaces its stored credentials.

OAuth and app-install providers (Stripe, Shopify, Supabase, GitHub, WooCommerce, Meta) cannot be connected here: their flows need a browser, so they return a 400 pointing at the dashboard. Use [Integration Catalog](/api-reference/integrations/catalog) to discover each connectable provider's exact fields via `connectFields`.

Requires an API key with the `integrations:manage` scope.

## Request

<ParamField body="provider" type="string" required>
  One of `polar`, `paddle`, `dodo`, `whop`, `creem`, `chargebee`, `clerk`,
  `posthog`, `affonso`.
</ParamField>

<ParamField body="webhookSecret" type="string" required>
  Signing secret of the webhook you create at the provider, pointed at the
  returned `webhookUrl`. For Chargebee, pass the webhook's basic-auth
  credentials as `username:password`.
</ParamField>

<ParamField body="apiKey" type="string">
  Provider API key. Required for every provider except Clerk and PostHog.
</ParamField>

<ParamField body="providerAccountId" type="string">
  Provider account ID. Required for Paddle (seller ID), Dodo (business ID), Whop
  (company ID, `biz_...`), Creem (store ID), and Chargebee (site name). Polar
  resolves it from the API key; Clerk, PostHog, and Affonso derive it.
</ParamField>

<ParamField body="settings" type="object">
  PostHog only: `{ syncAllEvents?: boolean, eventAllowlist?: string[] }`. Defaults to syncing every non-internal event.
</ParamField>

<ParamField body="historyImport" type="object">
  PostHog only: `{ region: "us" | "eu", projectId: string, personalApiKey: string }`. Imports the project's event history after connecting; the personal API key needs query read access.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/integrations/connect" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "paddle",
    "apiKey": "pdl_live_apikey_...",
    "webhookSecret": "pdl_ntfset_...",
    "providerAccountId": "12345"
  }'
```

## Response fields

<ResponseField name="integration" type="object">
  The connected integration, in the same shape as [List
  Integrations](/api-reference/integrations/list). Credentials are never
  included.
</ResponseField>

<ResponseField name="webhookUrl" type="string">
  URL to configure in the provider's webhook settings with the same secret.
</ResponseField>

<ResponseField name="revenueSyncQueued" type="boolean">
  Payment providers only: whether the initial revenue backfill was queued.
</ResponseField>

<ResponseField name="backfillQueued" type="boolean">
  Affonso only: whether the affiliate backfill was queued.
</ResponseField>

<ResponseField name="history" type="object">
  PostHog only: `{(requested, queued, error)}` for the optional history import.
  The webhook connection succeeds even when queueing the import failed.
</ResponseField>

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "integration": {
      "id": "int_abc123",
      "provider": "paddle",
      "name": "Paddle",
      "providerAccountId": "12345",
      "isActive": true,
      "syncEnabled": true,
      "syncStatus": null,
      "connectedAt": "2026-08-02T10:00:00.000Z"
    },
    "webhookUrl": "https://api.sequenzy.com/api/webhooks/paddle/comp_123",
    "revenueSyncQueued": true
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Stripe cannot be connected through the API: its connection runs an OAuth, app-install, or plugin flow that needs a human in the dashboard. Connect it from Settings -> Integrations."
  }
  ```

  ```json 400 Invalid provider credential theme={null}
  {
    "success": false,
    "error": "Invalid Polar API key. Please check and try again."
  }
  ```

  ```json 400 Missing provider permissions theme={null}
  {
    "success": false,
    "error": "The Whop API key is missing one or more required read permissions."
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": "This Paddle account is already connected to \"Other Workspace\""
  }
  ```
</ResponseExample>