Integrations Best Practices

Circuit-break vendor calls; do not block the request thread on unbounded external latency.

How to Use This List

• Review before adding a new SaaS SDK dependency
• Require integration design doc for payments and PII flows
• Pair with Integration Failure Playbook
• Load test with vendor mock 503 responses

A - Architecture

• SDK calls only from integration service modules - not route handlers.
• Singleton client per vendor per process with explicit timeout.
• Vendor errors mapped to AppError with stable codes for clients.
• Correlation id logged on every outbound request.
• Async queue for slow or non-critical vendor work (email, PDF, CRM sync).

B - Reliability

• Timeout per request (typically 5-15s) - see Timeouts Everywhere.
• Retry with exponential backoff + jitter for idempotent ops only.
• Circuit breaker on critical path vendors - see Circuit Breakers.
• Honor Retry-After on 429 from partners.
• Total deadline budget for user-facing requests documented.

C - Webhooks Inbound

• Signature verification on raw body before JSON parse.
• Idempotent handler on vendor event id unique constraint.
• Return 2xx after durable enqueue, not after full processing.
• Separate webhook route from express.json() global parser.
• DLQ or failed event table for manual replay.

D - Payments and SMS (Stripe/Twilio)

• Idempotency-Key on Stripe creates - see Stripe, Twilio & SDK Patterns.
• Test keys only in non-prod environments and CI.
• Stripe apiVersion pinned in code.
• Twilio inbound signature validated on all webhooks.
• No card data or secrets in logs - redact serializers.

E - Security and Compliance

• API keys in secrets manager, rotated on schedule.
• Least privilege IAM for AWS SDK integrations.
• SSRF guards on user-supplied URLs calling outbound fetch - see SSRF Guards.
• Vendor DPAs signed when PII leaves your VPC.
• Dependency scanning on integration SDK packages.

F - Operations

• Synthetic health checks against vendor test endpoints.
• Dashboards: error rate, latency, breaker state per vendor.
• Status page subscriptions for Stripe, Twilio, AWS.
• Runbook for vendor SEV1 with support macros.
• Post-outage reconciliation for payments (DB vs vendor dashboard).

FAQs

How many retries in HTTP handler?

0-2 quick retries max. Bulk retry in worker queue.

SDK auto-retry on or off?

Either SDK or app retry - not both unconfigured. Stripe: enable with idempotency keys.

Mock vendors in CI?

Required for unit tests. Contract tests optional against sandbox weekly.

Multiple environments webhooks?

Separate endpoint URLs and signing secrets per env.

When to fork vendor SDK?

Almost never. Wrap in service; upstream issues go to vendor or thin patch.

GraphQL to REST partners?

Same timeout/retry/idempotency rules via got/axios client.

Blocking vs non-blocking integrations?

Blocking only when user waits for result. Everything else queue.

Vendor SDK bundle size?

Import modular clients (AWS v3 style). Tree-shake Stripe if using subset builds.

Biggest production miss?

No timeout on outbound call - thread pool stall under vendor slowness.

New integration checklist item #1?

Read vendor retry, idempotency, and webhook docs before writing code.

Related

• Integrations Basics - service boundary
• Webhook Verification - HMAC inbound
• Retry & Outbound Resilience - backoff
• Integration Failure Playbook - incidents
• Resilience Best Practices - cross-cutting

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.