Third Party Integrations

Third-Party Integrations

Purpose

Integrate external services (payments, messaging, AI, CRM, etc.) so their failures, quirks, and API changes stay contained: one isolated client per provider, resilient calls, mapped errors, and testability without hitting live services.

When to Use

• When the backend calls any external API.
• Not for inbound events (webhooks) or file/object storage specifics (file-storage) — though their provider clients follow these rules.

Inputs

• Provider list with the operations used, criticality, and cost per call.
• Failure tolerance per operation (blocking a user vs degradable).

Discovery Questions

• Per provider: what operations, what rate limits/quotas, what does an outage do to your product?
• Sandbox/test environment available? How do dev/staging avoid production side effects (real emails, real charges)?
• Which calls belong in the request path vs background-jobs?

Responsibilities

• Isolate each provider behind your own interface (a service/port the domain calls); provider SDK types never leak into domain code — swapping or mocking stays possible.
• Handle credentials per backend-security: env/secret-store, per-environment keys, rotation story, never logged.
• Make every call bounded: explicit timeouts, retries with backoff + jitter only on idempotent/retryable operations, and circuit-breaking/degradation for critical-path providers — an external 30s hang must not become your 30s hang.
• Map provider errors into your taxonomy (backend-error-handling); respect provider rate limits (client-side throttling where needed).
• Separate environments: sandbox keys + fake/sink modes in dev/staging so tests never charge cards or email customers.
• Plan testing: contract-level mocks/stubs of your interface, plus a thin recorded/sandbox integration test per provider (backend-integration-testing).
• Track usage/cost where metered (AI, SMS) — alert on anomalies (backend-observability, ties to captcha-abuse-prevention for abuse-driven cost).

Required Workflow

1. Inventory providers, operations, criticality, quotas.
2. Define the interface per provider; place calls (request path vs background).
3. Set timeout/retry/breaker policy per operation class.
4. Define error mapping + degradation behavior.
5. Set environment separation + test strategy.
6. Specify tests: timeout honored, retry only on retryable, outage degrades as designed, sandbox isolation verified.

Decision Rules

• Non-idempotent external calls (charges, sends) retry only with provider idempotency keys — otherwise never blind-retry.
• Slow-but-optional providers leave the request path (background-jobs).
• Critical-path providers need a recorded outage behavior (fail closed, degrade, queue) — "we go down too" is a decision to make consciously, not discover.
• New providers are stack/vendor decisions — user approval (../../stack-recommendation), including data-sharing implications (../../../system/SECURITY_RULES.md).

Rules

• One client module per provider; no SDK calls scattered through services.
• Every external call has a timeout — no unbounded awaits.
• Provider responses are inputs: validate shape (backend-validation) before trusting.

Anti-Patterns

• Provider SDK objects passed around the domain.
• Retrying a charge without an idempotency key.
• No timeout — thread-pool/event-loop starvation during provider brownouts.
• Production keys in dev; test runs sending real emails.
• Catching provider errors and rethrowing their raw bodies to clients.

Validation Checklist

• Provider inventory with criticality + quotas.
• Interface isolation per provider.
• Timeouts, selective retries (+ idempotency keys), breaker/degradation per class.
• Error mapping into the taxonomy.
• Environment separation (sandbox/sink) enforced.
• Tests: timeout, retry policy, outage behavior, no live side effects in CI.

Definition of Done

A recorded integration design — isolated interfaces, bounded resilient calls, mapped errors, environment separation, and a test strategy that never hits production providers from CI.

Related Skills

webhooks, background-jobs, backend-error-handling, backend-security, backend-observability, backend-integration-testing, email-notifications, ../../dependency-audit (SDK health).

Related Knowledge

../../../knowledge/ (vendor contracts, quotas, data-sharing constraints).

Related References

../../../references/backend/integrations/ (provider notes, when populated).

Context Loading Guidance

• Requires: provider/operation inventory, criticality, environment model.
• Does not require: full SDK docs, unrelated domains.
• May load: backend-error-handling (mapping), background-jobs (placement).
• Stop when: per-provider interface + resilience + test design is recorded.

Token Efficiency Guidance

One table row per provider (operations, criticality, timeout/retry, outage behavior, sandbox); link vendor docs instead of summarizing them.