Integrations Overview

Connect Selwise events to GA4, Meta, Google Ads, webhooks, and data layer workflows.

Audience: Integration engineers and technical marketers managing downstream analytics and ad channels.

Critical: All management endpoints are site-scoped under /api/v1/sites/:siteId/integrations/* and require authenticated site access.

GA4 Meta Google Ads Operations

Who This Page Is For

Use this page when you need the full integration control plane: provider config, mapping, data layer settings, webhooks, health checks, and delivery logs.

Quick Start (2-5 Minutes)

List configured integrations

Get current provider setup for a site.

GET /api/v1/sites/:siteId/integrations

Configure provider

Create or update provider config with mapping/filtering.

PUT /api/v1/sites/:siteId/integrations/:provider

Verify health

Inspect dashboard-oriented health summary.

GET /api/v1/sites/:siteId/integrations/health

Run connectivity test

Execute provider test call before turning traffic on.

POST /api/v1/sites/:siteId/integrations/:provider/test

Inspect logs and mapping defaults

Review delivery logs and provider default mapping contract.

GET /api/v1/sites/:siteId/integrations/:provider/logs
GET /api/v1/sites/:siteId/integrations/:provider/mappings

Core integration endpoints

GET    /api/v1/sites/:siteId/integrations
GET    /api/v1/sites/:siteId/integrations/health
GET    /api/v1/sites/:siteId/integrations/:provider
PUT    /api/v1/sites/:siteId/integrations/:provider
DELETE /api/v1/sites/:siteId/integrations/:provider
POST   /api/v1/sites/:siteId/integrations/:provider/test
GET    /api/v1/sites/:siteId/integrations/:provider/logs
GET    /api/v1/sites/:siteId/integrations/:provider/mappings
GET    /api/v1/sites/:siteId/integrations/data-layer
PUT    /api/v1/sites/:siteId/integrations/data-layer
GET    /api/v1/sites/:siteId/integrations/webhooks
POST   /api/v1/sites/:siteId/integrations/webhooks

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`provider`	Required	`ga4 \| meta \| gads \| google_ads`	Provider routes	Integration target provider identifier.
`enabled`	Optional	`boolean`	Provider update payload	Enable or disable forwarding for provider.
`config`	Optional	`object`	Provider update payload	Provider credentials and options.
`eventMapping / reverseEventMapping`	Optional	`Record<string,string>`	Provider update payload	Forward and reverse mapping contracts.
`eventFilters`	Optional	`Record<string, {enabled,conditions[]}>`	Provider update payload	Conditional forwarding gates.
`testMode`	Optional	`boolean`	Provider update payload	Logs events without sending to downstream provider.

Currency Forwarding

For purchase/order events, provider currency is resolved in this order:

Event currency
Order currency
Site currency (Site.currency)
EUR

Mixed-currency values are not converted. Downstream payloads keep the resolved source currency.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Need all provider configs for one site	GET /integrations	Single snapshot of integration state.
Need dashboard health view	GET /integrations/health	Fast operational status summary.
Need provider config update	PUT /integrations/:provider	Primary write path for provider settings.
Need pre-launch validation	POST /integrations/:provider/test	Connectivity and payload sanity check.
Need delivery diagnostics	GET /integrations/:provider/logs	Inspect failures and retries.

Common Errors and Fixes

Provider shows healthy but no conversions downstream

Cause: eventMapping or eventFilters blocking relevant events.

Fix: Review mapping/filter settings and test with representative purchase events.

Provider update accepted but credentials fail later

Cause: Credentials syntactically valid but not authorized at provider.

Fix: Run provider test endpoint and verify downstream account permissions.

Unexpected route conflict with webhooks

Cause: Incorrect assumption that webhooks are provider values.

Fix: Use dedicated /integrations/webhooks routes for webhook management.

Events appear in logs but not in provider

Cause: testMode enabled.

Fix: Disable testMode after validation period.

Production Checklist

Each provider configuration is validated with test endpoint before launch.Required
eventMapping and filters are documented per site.Required
testMode is disabled in production after QA.Required
Health and logs are monitored for delivery failures.Required
Webhook and data-layer configs are reviewed with provider configs together.Required