Third Party Integration

Third-Party Integration

Integrate reliably with external APIs and services: adapters, webhooks, payments, and testing.

Core principle: Treat every third-party API as unreliable. It will go down, change, rate-limit you, and send duplicate webhooks. Design for all of it.

When to Use

• Integrating with any external API or service
• Implementing webhook receivers
• Adding payment processing (Stripe)
• Isolating third-party code behind an interface
• Writing tests for code that calls external services

When NOT to Use

• Internal service-to-service calls (use api-design skill)
• Database connections (use database-design skill)

Integration Architecture

Anti-Corruption Layer (Adapter Pattern)

Never let third-party models bleed into your domain. Always translate at the boundary.

// External: Stripe's model
interface StripePaymentIntent {
  id: string;
  amount: number;
  currency: string;
  status: 'requires_payment_method' | 'succeeded' | 'canceled';
}

// Internal: your domain model
interface Payment {
  id: PaymentId;
  amountCents: number;
  currency: string;
  status: 'pending' | 'complete' | 'failed';
}

// Adapter: translates at the boundary
class StripePaymentAdapter {
  toDomain(intent: StripePaymentIntent): Payment {
    return {
      id: new PaymentId(intent.id),
      amountCents: intent.amount,
      currency: intent.currency,
      status: this.mapStatus(intent.status),
    };
  }

  private mapStatus(stripeStatus: string): Payment['status'] {
    const map: Record<string, Payment['status']> = {
      'succeeded': 'complete',
      'requires_payment_method': 'pending',
      'canceled': 'failed',
    };
    return map[stripeStatus] ?? 'pending';
  }
}

Interface First

Define your own interface before integrating:

// Define what YOU need — not what Stripe provides
interface PaymentService {
  charge(params: ChargeParams): Promise<Payment>;
  refund(paymentId: PaymentId, amountCents: number): Promise<void>;
  getPayment(paymentId: PaymentId): Promise<Payment>;
}

// Production implementation
class StripePaymentService implements PaymentService { ... }

// Test implementation
class FakePaymentService implements PaymentService { ... }

API Client Patterns

Authentication

// Bearer token (most common)
headers: { Authorization: `Bearer ${apiKey}` }

// API Key in header
headers: { 'X-API-Key': apiKey }

// Basic auth
headers: { Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}` }

Resilient API Client

class ApiClient {
  constructor(
    private baseUrl: string,
    private apiKey: string,
    private timeout = 10_000,
  ) {}

  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
    const url = `${this.baseUrl}${path}`;
    
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
      signal: AbortSignal.timeout(this.timeout),
    });

    if (response.status === 429) {
      const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
      await sleep(retryAfter * 1000);
      return this.request(path, options);  // Retry once
    }

    if (!response.ok) {
      throw new ApiError(response.status, await response.text(), url);
    }

    return response.json();
  }
}

Rate Limiting

Handle 429s with Retry-After (shown in resilient client above). For concurrent request limiting, use p-limit or bottleneck in production rather than a hand-rolled queue.

Webhook Handling

Signature Verification (Stripe example)

Always verify the signature before processing. An unverified webhook endpoint can be exploited.

app.post('/webhooks/stripe',
  express.raw({ type: 'application/json' }),  // Raw body required for verification
  async (req, res) => {
    const sig = req.headers['stripe-signature'] as string;
    
    let event: Stripe.Event;
    try {
      event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
    } catch (err) {
      logger.warn('Invalid webhook signature', { err });
      return res.status(400).send('Webhook signature verification failed');
    }

    // Acknowledge immediately — process async
    res.status(200).json({ received: true });
    
    await processWebhookEvent(event);
  }
);

Idempotency

Webhooks are delivered at-least-once. Always deduplicate:

async function processWebhookEvent(event: Stripe.Event) {
  // Check if already processed
  const processed = await db.query(
    'SELECT id FROM webhook_events WHERE event_id = $1',
    [event.id]
  );
  if (processed.rows.length > 0) {
    logger.info('Duplicate webhook — skipping', { eventId: event.id });
    return;
  }

  // Process
  await handleEvent(event);

  // Record as processed
  await db.query(
    'INSERT INTO webhook_events (event_id, type, processed_at) VALUES ($1, $2, NOW())',
    [event.id, event.type]
  );
}

Payment Integration (Stripe)

Idempotent Charge

async function chargeCustomer(order: Order): Promise<Payment> {
  const intent = await stripe.paymentIntents.create(
    {
      amount: order.totalCents,
      currency: 'usd',
      customer: order.stripeCustomerId,
      payment_method: order.paymentMethodId,
      confirm: true,
      metadata: { order_id: order.id },
    },
    {
      idempotencyKey: `charge-${order.id}`,  // Safe to retry on network error
    }
  );

  return paymentAdapter.toDomain(intent);
}

Subscription Lifecycle

Key webhooks: customer.subscription.created → provision, invoice.payment_succeeded → extend access, invoice.payment_failed → dunning email, customer.subscription.deleted → revoke access. States: trialing → active → past_due → canceled/unpaid.

Testing Third-Party Integrations

Fake Implementation for Unit Tests

class FakePaymentService implements PaymentService {
  private payments = new Map<string, Payment>();

  async charge(params: ChargeParams): Promise<Payment> {
    const payment: Payment = {
      id: new PaymentId(`pay_fake_${Date.now()}`),
      amountCents: params.amountCents,
      currency: params.currency,
      status: 'complete',
    };
    this.payments.set(payment.id.value, payment);
    return payment;
  }

  async getPayment(id: PaymentId): Promise<Payment> {
    return this.payments.get(id.value) ?? throw new NotFoundError();
  }
}

// Usage in tests
const paymentService = new FakePaymentService();
const orderService = new OrderService(paymentService);
await orderService.checkout(order);

Common Failure Modes

Verification Checklist

• All third-party models translated at boundary (adapter pattern)
• Own interface defined before integrating (for testability)
• Webhook signatures verified before processing
• Webhook handler deduplicates by event ID
• Webhook responds 200 immediately, processes async
• API calls have timeouts (10s default)
• Idempotency keys used for payment/state-changing calls
• Rate limiting handled (429 → retry with Retry-After)
• API keys in environment variables, never in code
• Fake implementation exists for unit testing
• Sandbox/test mode used in staging and development