Skip to main content

​
Provider Connect and Settings

These endpoints power provider-specific integration onboarding and configuration.

​
Endpoints

​
Slack

  • GET /api/integrations/slack/connect
  • GET /api/integrations/slack/callback

​
HubSpot

  • GET /api/integrations/hubspot/connect
  • GET /api/integrations/hubspot/callback
  • PATCH /api/integrations/hubspot/settings

​
Stripe Connect

  • GET /api/integrations/stripe/connect
  • GET /api/integrations/stripe/callback
  • GET /api/integrations/stripe/status
  • PATCH /api/integrations/stripe/settings
  • DELETE /api/integrations/stripe/disconnect

​
Shopify pixel bridge

  • OPTIONS /api/integrations/shopify/pixel
  • POST /api/integrations/shopify/pixel?installationId=...

​
Auth and permission model

​
Connect/settings/status/disconnect

  • Requires authenticated workspace session.
  • Typical permission: integrations:manage (status uses integrations:read).
  • Integrations entitlement gate applies to connect/setup routes.

​
Callback routes

  • OAuth callbacks are browser redirects, not JSON API mutations.
  • Callback verifies OAuth state, active user session, and membership to target workspace.
  • Success/failure returns dashboard redirect with status query params.

​
Shopify pixel

  • Public CORS-enabled ingestion route.
  • No dashboard auth; verifies installationId and installation type.
  • Rate limited by IP.

​
Settings payloads

​
Stripe settings

PATCH /api/integrations/stripe/settings 
{
  "freeTrials": {
    "enabled": true,
    "trackQuantity": false
  }
}

​
HubSpot settings

PATCH /api/integrations/hubspot/settings 
{
  "leadTriggerEvent": "dealCreated",
  "closedWonDealStageId": "closedwon"
}
Supported leadTriggerEvent values:
  • dealCreated
  • lifecycleStageReached

​
Shopify pixel payload

POST /api/integrations/shopify/pixel?installationId=inst_xxx 
{
  "checkoutToken": "chk_123",
  "clickId": "clk_abc12345",
  "refCode": "partner_ref_code"
}
Rules:
  • checkoutToken required.
  • At least one of clickId or refCode required.
  • Invalid click-id formats are discarded.
  • Stores checkout-to-attribution mapping for later conversion attribution.

​
Common errors

  • 400: invalid settings payload, missing callback params, invalid Shopify payload
  • 401/403: missing auth, workspace access denied, permission denied
  • 404: provider installation not found where required
  • 422: provider not configured in environment
  • 503: cache/state backend unavailable for OAuth state handling