<string, unknown> ): Promise<void> { const idempotencyKey = crypto.randomUUID(); const body = JSON.stringify({ event, payload, idempotencyKey });

const response = await fetch(tenant.webhookEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Partner-Event': event, 'X-Idempotency-Key': idempotencyKey, 'X-Signature': crypto .createHmac('sha256', tenant.webhookSecret) .update(body) .digest('hex'), }, body, });

if (!response.ok) { // Queue for exponential backoff retry await retryQueue.enqueue({ tenantId: tenant.id, event, payload, attempt: 1 }); } }

### Step 4: Add Attribution & Analytics Pipeline

Partnerships fail without measurable ROI. An attribution pipeline tags incoming traffic, tracks conversion funnels, and calculates partner-specific LTV/CAC.

```typescript
// src/analytics/attribution.service.ts
import { db } from '../database';

export async function recordPartnerAttribution(
  partnerId: string,
  userId: string,
  touchpoint: string,
  metadata: Record<string, unknown>
): Promise<void> {
  await db.query(
    `INSERT INTO partner_attribution 
     (partner_id, user_id, touchpoint, metadata, created_at)
     VALUES ($1, $2, $3, $4, NOW())
     ON CONFLICT (partner_id, user_id, touchpoint) 
     DO UPDATE SET metadata = EXCLUDED.metadata`,
    [partnerId, userId, touchpoint, JSON.stringify(metadata)]
  );
}

export async function calculatePartnerROI(
  partnerId: string,
  windowDays: number = 30
): Promise<{ revenue: number; cpl: number; roi: number }> {
  const result = await db.query(
    `SELECT 
       SUM(revenue) as revenue,
       COUNT(DISTINCT user_id) as conversions,
       COALESCE(SUM(cost), 0) as total_cost
     FROM partner_attribution pa
     JOIN partner_costs pc ON pa.partner_id = pc.partner_id
     WHERE pa.partner_id = $1 
       AND pa.created_at > NOW() - INTERVAL '${windowDays} days'`,
    [partnerId]
  );

  const { revenue, conversions, total_cost } = result.rows[0];
  const cpl = conversions > 0 ? total_cost / conversions : 0;
  const roi = total_cost > 0 ? (revenue - total_cost) / total_cost : 0;

  return { revenue, cpl, roi };
}

Architecture Decisions & Rationale

• Tenant-scoped API keys over shared credentials: Prevents cross-partner data leakage and enables granular revocation without disrupting other integrations.
• Webhook idempotency keys: Eliminates duplicate event processing caused by network retries or partner-side queue redrives.
• Exponential backoff retry queue: Ensures delivery during partner outages without overwhelming downstream services. Dead-letter queues capture unprocessable events for manual review.
• Feature flags per partner: Enables controlled rollouts, A/B testing of partner-specific endpoints, and instant rollback without code deployments.
• Attribution pipeline decoupled from core transactional DB: Prevents query contention. Uses append-only logging with materialized views for ROI calculations.

Pitfall Guide

1. Hardcoding partner endpoints or credentials: Embedding URLs or secrets in application code forces redeployments for every partner change. Store endpoints, secrets, and rate limits in a tenant configuration store with hot-reload capability.

2. Ignoring webhook idempotency: Partners will retry failed deliveries. Without idempotency keys, your system processes duplicates, corrupts analytics, and triggers duplicate billing. Implement idempotency at the ingestion layer, not the business logic layer.

3. Skipping partner sandbox environments: Onboarding partners directly into production breaks your SLA and exposes real user data. Provision isolated sandbox tenants with synthetic data, mirrored API contracts, and independent webhook endpoints.

4. Flat rate limits across all tiers: A single noisy partner can exhaust shared connection pools or database throughput. Implement tiered rate limiting with burst allowances and circuit breakers that degrade gracefully rather than failing hard.

5. Missing attribution pipeline: Without tagged touchpoints and conversion tracking, partnerships become unmeasurable cost centers. Attribute at the point of entry (UTM, referral header, or API key) and track through the full funnel.

6. Over-customizing payloads per partner: Building unique data shapes for each partner creates maintenance debt. Standardize on a core schema, then use a transformation layer to map partner-specific requirements. Version the schema and enforce contract testing.

7. No dead-letter queue for failed webhooks: Silent failures destroy partner trust. Route unretryable events to a DLQ with structured error context, alerting, and manual replay capabilities.

Production Best Practices:

• Use OpenAPI/Swagger contracts for all partner endpoints. Generate client SDKs automatically.
• Implement mutual TLS or signed JWTs for enterprise partners requiring higher assurance.
• Cache partner tenant configuration with short TTLs (30–60s) to balance consistency and latency.
• Run chaos tests on webhook delivery paths quarterly to validate retry and DLQ behavior.
• Instrument partner-specific dashboards: latency, error rates, throughput, and attribution accuracy.

Production Bundle

Action Checklist

• Define partner tenant model: Establish id, tier, status, and feature flag structure before building integrations.
• Implement API gateway routing: Authenticate via Bearer tokens, resolve tenant context, and inject into downstream services.
• Build webhook dispatcher: Add signature verification, idempotency keys, and exponential backoff retry logic.
• Provision sandbox tenants: Create isolated environments with synthetic data and independent endpoints for onboarding.
• Deploy attribution pipeline: Tag touchpoints at ingestion, log conversions, and calculate ROI with windowed aggregations.
• Configure tiered rate limits: Apply per-tenant limits with burst allowances and circuit breakers to prevent noisy-neighbor degradation.
• Set up dead-letter queues: Capture failed webhook deliveries with structured error context and manual replay controls.
• Publish OpenAPI contracts: Version all partner endpoints and generate client SDKs to reduce integration friction.

Decision Matrix

Configuration Template

# config/partners-engine.yaml
partner:
  gateway:
    auth: bearer
    tenant_resolution_ttl_sec: 45
    rate_limit:
      default:
        requests_per_minute: 60
        burst_size: 10
      tiers:
        sandbox:
          requests_per_minute: 20
          burst_size: 5
        enterprise:
          requests_per_minute: 300
          burst_size: 50
  webhooks:
    retry:
      max_attempts: 5
      backoff_base_sec: 2
      backoff_multiplier: 2
    dlq:
      enabled: true
      retention_days: 30
  attribution:
    touchpoint_sources: [utm, referral_header, api_key]
    roi_window_days: 30
    materialized_view_refresh_sec: 300
  security:
    enterprise:
      mtls: enabled
      jwt_signing_algo: RS256
      audit_logging: enabled

Quick Start Guide

1. Initialize the tenant configuration store: Run npm run db:migrate to apply the partner schema, then seed a sandbox tenant using npm run partner:seed -- --tier=sandbox.
2. Start the gateway: Execute npm run dev to launch the Express server with middleware chain: resolvePartnerTenant → rateLimiter → webhookDispatcher.
3. Test webhook delivery: Use curl -X POST http://localhost:3000/api/v1/partners/webhooks/test -H "Authorization: Bearer <SANDBOX_API_KEY>" to trigger a signed event. Verify signature and idempotency in the logs.
4. Validate attribution: Insert a test touchpoint via npm run analytics:test-attribution -- --partner-id=<ID>, then run npm run analytics:roi -- --partner-id=<ID> --window=30 to confirm ROI calculation.
5. Promote to production: Switch NODE_ENV=production, enable DLQ alerts, and configure your CI/CD pipeline to run OpenAPI contract tests before deployment.