magnus919_agent-skills/backend-engineering/references/integration-patterns.md

Integration Patterns

External Call Resilience

Pattern	What it protects against	Implementation
Retry with backoff	Transient failures	Exponential backoff + jitter, max retries
Circuit breaker	Sustained failures	Open after N failures, half-open after timeout
Timeout	Hanging connections	Connect + read + write timeouts per operation
Bulkhead	Cascading failures	Separate thread pool / connection pool per dependency
Idempotency key	Duplicate requests	Client-generated key, server deduplicates

Idempotency Key Pattern

POST /api/payments
Idempotency-Key: 7c3d5e8f-a1b2-4c3d-8e5f-6a7b8c9d0e1f

Aspect	Design
Key generation	Client UUID v4
Storage	Key-value store with TTL (24h)
First request	Process normally, store result keyed by idempotency key
Duplicate request	Return stored result, no side effects
Expired key	Process as new request
In-flight request	Return 409 Conflict

Webhook Verification

Mechanism	What it verifies	Implementation
HMAC signature	Payload integrity, sender authenticity	Shared secret → HMAC of body → compare header
Webhook secret	Sender identity	Pre-shared secret, rotated periodically
Timestamp freshness	Replay prevention	Reject webhooks older than N minutes

Message Queue Consumer Patterns

Pattern	When to use
At-least-once delivery	Default — requires idempotent processing
Exactly-once (dedup)	When duplicates are unacceptable — requires dedup store
Batch processing	High throughput, latency-tolerant
Dead letter queue	Messages that can't be processed after max retries

Every consumer should: acknowledge after processing, retry on transient failure, DLQ on permanent failure, and log at every stage.