Integrations Highlights Summary

Every highlight bullet from the 7 pages in this section, gathered on one page and grouped by the page it came from.

The Integration Boundary

• Every external vendor call needs a seam that owns retries, timeouts, and error translation in one place
• SDKs handle protocol details, not your resilience policy - timeouts and retry counts are still yours to set
• Inbound webhooks are integrations too, and need the same boundary discipline as outbound calls
• A boundary that leaks vendor-specific types and errors into your domain code has already failed at its job

Integrations Basics

• Never call Stripe/Twilio directly from route handlers
• Integration service owns retries, timeouts, and idempotency
• Secrets stay in env; SDK clients are singletons
• Map vendor errors to your AppError taxonomy
• Test with vendor sandbox/mocks at service boundary

Webhook Verification

• Verify HMAC signature on raw body before JSON parse
• Stripe/Twilio ship signing secrets per endpoint
• Reject stale timestamps to limit replay window
• Handlers must be idempotent - vendors retry
• Return 2xx quickly; heavy work goes to queue

Retry & Outbound Resilience

• Retry only idempotent methods or keyed mutations
• Exponential backoff with jitter prevents retry storms
• Cap max attempts and total deadline
• Classify 4xx - most should not retry
• Circuit breaker stops calling sick vendors

Stripe, Twilio & SDK Patterns

• Stripe idempotency keys on all POST creates
• Twilio status callbacks need public HTTPS URL
• Pin SDK versions; Stripe apiVersion explicit
• Test mode keys only in non-prod environments
• Expand objects sparingly - payload size and latency

Integration Failure Playbook

• Detect vendor failure via error rate and latency SLOs
• Circuit breaker opens before thread pool exhaustion
• Degraded mode returns partial features with clear UX copy
• Status page and support macros ready before outage
• Post-incident: vendor ticket + internal retro

Integrations Best Practices

• Wrap every vendor SDK behind an integration service
• Timeouts on all outbound calls - no infinite hang
• Verify webhook signatures on raw body
• Idempotency for POST creates and webhook handlers
• Circuit breaker before vendor takes down your API