Integrations

Capability	Common providers	Watch out for
Payments	Stripe, Adyen, Braintree, Square	PCI scope, idempotency, webhook signature verification, 3DS / SCA flows.
Email (transactional)	SendGrid, Postmark, AWS SES, Resend	SPF / DKIM / DMARC, bounce + complaint handling, deliverability reputation.
SMS & voice	Twilio, Vonage, MessageBird	Country regulations (10DLC, A2P), opt-out handling, cost surprises.
Push notifications	APNs, FCM, OneSignal	Token rotation, silent vs visible payloads, quiet hours.
Identity	Auth0, Okta, Cognito, Clerk, WorkOS	SSO contracts (SAML, OIDC), SCIM provisioning, vendor lock-in.
Search	Algolia, Elastic, Typesense, Meilisearch	Index drift vs source of truth, reindex storms.
AI / LLMs	Anthropic, OpenAI, Bedrock, Vertex	Streaming, token costs, rate limits, prompt injection from upstream data.
Analytics & CRM	Segment, HubSpot, Salesforce, Intercom	PII handling, GDPR deletion, eventual consistency.
Storage & CDN	S3, GCS, Cloudflare R2, Cloudinary	Signed URLs, lifecycle rules, egress costs.

Timeouts, Retries, and Backoff

• Set an explicit connect timeout and read timeout. Default-infinite timeouts hang your service.
• Retry on transient failures (5xx, network errors, 429) with exponential backoff + jitter.
• Never retry non-idempotent calls without an idempotency key — duplicate charges and double-sent emails come from this.
• Cap total retry budget; a 30-second cascade on every request takes down the whole service.

Idempotency Keys

Most modern APIs (Stripe, Square, AWS) accept an Idempotency-Key header. Generate one per logical operation and persist it alongside the operation. Reusing the key lets you retry safely without double-side-effects.

Circuit Breakers & Bulkheads

Circuit breaker: after N consecutive failures, stop calling the dependency for a cool-off period. Fail fast with a fallback. Libraries: Resilience4j (JVM), Polly (.NET), opossum (Node).

Bulkhead: isolate resources per dependency (separate thread pools / semaphores) so one slow vendor can't starve every request thread.

Anti-Corruption Layer

Wrap each vendor in an internal interface — EmailSender, PaymentProcessor. Your domain code talks to the interface, not to SendGrid's SDK. When you switch from SendGrid to Postmark in a year, you change one file.

Secrets Management

• Never commit API keys. Use AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or Doppler.
• Inject at runtime via env vars or sidecar — not baked into images.
• Rotate on a schedule and after any suspected leak. Use scoped keys (read-only / write-only) wherever the vendor offers them.
• Have a kill-switch: a way to revoke a vendor key in < 5 minutes.

• Verify the signature. Stripe, GitHub, Slack, etc. all sign their payloads with HMAC. An unverified webhook endpoint is an open door.
• Respond quickly. Acknowledge with 2xx in < 1–2 seconds. Hand the heavy work to a queue (see Background Jobs).
• Be idempotent. Vendors retry on timeouts and the same event will arrive twice. Dedupe by event ID.
• Replay capability. Log raw payloads so you can re-process a missed window after an outage.
• Order isn't guaranteed. A "subscription.updated" can arrive before the "customer.created" you expected. Design for out-of-order events.

Any feature that fetches a user-supplied URL (image previews, OAuth callbacks, webhook test buttons) is an SSRF risk — the user can point it at your cloud metadata service or internal admin endpoints.

• Allow-list schemes (https only) and resolve DNS yourself; block private IP ranges (RFC 1918, link-local, IMDS).
• Run outbound calls from a network that cannot reach internal services or the metadata endpoint.
• Tag and rate-limit egress per vendor — useful for cost control too.

• Inline calls on the request path — a 12s vendor latency becomes a 12s user wait. Move non-essential work to a queue.
• Trusting webhook payloads to be correct. Treat them as a hint; re-fetch from the vendor's API for the canonical state.
• No vendor-down plan. Decide in advance: degrade gracefully, queue and retry, or fail loudly?
• Hard-coded vendor specifics leaking through your domain — Stripe IDs in business logic, SendGrid templates in core code paths.
• Running integration tests against prod. Use sandbox modes; record/replay (VCR, MSW) in CI.