Integration Operations

Operations

Operate integrations in production with health checks, tests, logs, and controlled rollback patterns.

Audience: SRE, analytics operations, and technical marketers responsible for integration reliability.

Critical: Operational flow should always run in order: config -> test -> health check -> log monitoring -> rollback if required.

Integrations Overview Webhooks Errors and Retries

Who This Page Is For

Use this page when you need a repeatable operational runbook for integration changes, incident handling, and post-release monitoring.

Quick Start (2-5 Minutes)

Snapshot current state

Read integration list and health before any changes.

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

Apply controlled change

Update provider or webhook/data-layer config.

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

Run immediate test

Validate channel behavior before full traffic confidence.

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

Inspect logs

Verify successful sends and inspect failures.

GET /api/v1/sites/:siteId/integrations/:provider/logs?limit=100

Rollback if needed

Disable provider or set testMode while investigating incident.

{ "enabled": false } or { "testMode": true }

Operational 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
POST /api/v1/sites/:siteId/integrations/:provider/test
GET  /api/v1/sites/:siteId/integrations/:provider/logs
GET  /api/v1/sites/:siteId/integrations/webhooks/:webhookId/logs

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`siteId`	Required	`uuid`	All operational endpoints	Site being operated.
`provider`	Conditional	`ga4 \| meta \| gads \| google_ads`	Provider-specific operations	Integration target key.
`limit / offset`	Optional	`number`	Logs endpoints	Pagination for operational log review.
`enabled / testMode`	Optional	`boolean`	Rollback and traffic control	Fast control knobs during incidents.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Pre-change baseline	/integrations + /integrations/health	Establish before-state for safe rollout.
Post-change verification	/integrations/:provider/test	Immediate confidence check.
Incident diagnosis	/integrations/:provider/logs	Detailed send and error visibility.
High-risk issue mitigation	enabled=false or testMode=true	Contain impact while debugging.
Webhook delivery issue triage	/integrations/webhooks/:webhookId/logs	Endpoint-specific operational telemetry.

Common Errors and Fixes

Health is green but downstream platform shows gaps

Cause: Health may reflect config/connectivity while event filters suppress payloads.

Fix: Audit mapping and filter configuration plus logs.

Intermittent failures with retries

Cause: Provider or receiver rate limits / transient transport issues.

Fix: Review retry behavior and coordinate with provider limits.

Unexpected event volume drops after update

Cause: Config overwrite removed critical mappings.

Fix: Reapply known-good mapping snapshot and retest.

Cannot isolate failing integration quickly

Cause: No provider-level runbook separation.

Fix: Operate one provider at a time and validate sequentially.

Production Checklist

Every integration change has before/after snapshot records.Required
Provider test is mandatory after each config change.Required
Logs are monitored for at least one business cycle post-change.Required
Rollback controls (enabled/testMode) are documented per provider.Required
Operational ownership and escalation path is explicitly assigned.Required