Services

Integration architecture playbook

Connect SaaS platforms, internal APIs, queues, and automation workflows with clear contracts and controls.

Integrations move business state between systems. They also amplify failures when contracts, retries, ownership, or data boundaries are unclear. Use this playbook to design integrations that can be operated, debugged, and safely automated.

Integration types#

PatternBest forWatchouts
Synchronous API callUser-facing lookup or command that must complete now.Latency, dependency failures, cascading outages.
WebhookExternal system notifies you of state changes.Retries, signature verification, replay protection, ordering.
Queue/event streamAsynchronous work and fan-out to multiple consumers.Idempotency, schema evolution, dead letters, lag.
Batch import/exportLarge historical syncs or low-frequency reporting.Freshness, partial failures, sensitive files, reconciliation.
Reverse ETLUpdating SaaS tools from governed data products.Field ownership, consent, rate limits, deletion propagation.

Design checklist#

  • Who owns each side of the integration?
  • What is the source of truth for each field?
  • Is the flow command-oriented, event-oriented, or synchronization-oriented?
  • What happens if the receiver is down for minutes, hours, or days?
  • How are retries made safe and idempotent?
  • Which data fields are personal, regulated, secret, or customer-confidential?
  • How do operators reconcile drift between systems?

Implementation controls#

Contracts#

Define event/API contracts before implementation:

  • Schema and field meanings.
  • Required vs optional fields.
  • Versioning and compatibility rules.
  • Example payloads.
  • Error codes and retryability.
  • Ownership and escalation channel.

Use CloudEvents or a similar envelope for event-driven integrations so metadata such as ID, source, type, time, and subject are consistent.

Idempotency and reconciliation#

Every integration that can retry needs idempotency.

  • Use stable external IDs and idempotency keys.
  • Store processed event IDs with an expiration window.
  • Design updates as upserts where possible.
  • Add reconciliation jobs to compare source and destination state.
  • Keep dead-letter queues or failed-record tables with replay tooling.

Security#

  • Verify webhook signatures and timestamps.
  • Use scoped credentials per integration and environment.
  • Rotate secrets and disable unused integration users.
  • Avoid sending unnecessary personal data to third parties.
  • Log who configured the integration and which fields are mapped.

Observability#

Minimum integration dashboards:

  • Event/API volume by integration and operation.
  • Success, retry, and dead-letter rates.
  • End-to-end latency and queue lag.
  • Provider rate-limit responses.
  • Authentication/signature failures.
  • Reconciliation drift count.

Each integration should have a runbook with replay instructions, provider status links, credential rotation steps, and known rate limits.

Example integration contract#

yaml
1
name: crm-company-sync
2
owner: revenue-platform
3
source_of_truth: internal-customer-api
4
destination: crm-provider
5
pattern: queue-worker
6
schema_version: 2026-06-26.1
7
idempotency_key: company_id + updated_at
8
personal_data: false
9
retry_policy:
10
  max_attempts: 8
11
  backoff: exponential
12
  dead_letter_after: 24h
13
reconciliation:
14
  schedule: daily
15
  drift_threshold: 25 records

References#