Integration Service

Secure webhook ingestion, event routing, and business logic orchestration for third-party services.

What It Does

The Integration Service serves as the centralized hub for third-party service integrations, handling webhook ingestion, business logic execution, and event orchestration. It receives webhooks from external service providers, verifies their authenticity using cryptographic signatures, processes business logic specific to each integration, and routes validated events into the platform’s event bus. Currently focused on payment integrations (Stripe), it’s designed to expand and accommodate various types of third-party services as business needs evolve.

Key Capabilities

Capability	Description
Webhook Verification	Cryptographic signature validation using provider secrets
Business Logic Hub	Centralized processing of third-party service events
Raw Body Preservation	Maintains raw request body for signature verification
Event Publishing	Routes processed events to pub/sub topics
Secret Management	Secure retrieval of integration secrets from secret store
Event Filtering	RxJS-based type filtering for downstream consumers
Public Endpoints	Unauthenticated endpoints for external webhook delivery
Modular Architecture	Extensible design for multiple service integrations

How It Fits Together


┌──────────────┐
│ Third-Party  │
│   Service    │ (webhook)
└──────┬───────┘
       │
       ▼
┌─────────────────┐
│  Integration    │  verifies signature
│    Service      │  processes business logic
│ (Stripe, etc.)  │  publishes to topic
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Pub/Sub       │
│     Topic       │
└────────┬────────┘
         │
    ┌────┴─────┬─────────────┐
    ▼          ▼             ▼
┌──────┐  ┌──────┐     ┌──────────┐
│ Saga │  │ Saga │     │Background│
│  #1  │  │  #2  │     │  Tasks   │
└──────┘  └──────┘     └──────────┘

External webhooks are verified, processed through integration-specific business logic, transformed into platform events, and consumed by sagas and background tasks throughout the system.

Common Use Cases

Current (Payment/Stripe Integrations)

Subscription management: Process subscription lifecycle events (created, updated, canceled)
Payment processing: Handle payment succeeded/failed notifications
Refund tracking: Receive refund events and update order status
Customer updates: Sync customer information changes from payment provider
Dispute handling: Process chargeback and dispute notifications
Billing cycles: Track billing period changes and invoice generation

Future Expansion Possibilities

Communication services: SMS/email delivery notifications, status updates
Identity providers: User authentication events, profile changes
Analytics platforms: Event tracking, conversion notifications
E-commerce platforms: Order updates, inventory changes
CRM systems: Lead updates, contact management events
Logistics providers: Shipping notifications, delivery confirmations

What You Don’t Have to Build

HMAC signature verification for webhooks
Raw body preservation middleware
Webhook secret management and rotation
Signature timestamp validation
Replay attack protection
Pub/sub topic integration
Event wrapping and transformation
RxJS event filtering operators
Cloud function topic subscription generation
Provider SDK integration and testing
Modular multi-provider architecture
Conditional integration loading
Type-safe event handling
Error taxonomy for webhook failures
Comprehensive webhook lifecycle logging
Secret retrieval with fallback strategies
Public endpoint configuration for webhooks
Event routing to multiple consumers
Saga-compatible event streaming

Technical Details

Heavy-Lifting Features

1. Cryptographic Webhook Verification

Multi-layered signature validation for webhook authenticity across all integrations:


EventService.dispatchEvent() (Stripe implementation):
  - Preserves raw request body (required for signature verification)
  - Retrieves webhook secret from secure secret store
  - Uses provider SDK to verify signature (constructEvent)
  - Validates event structure and integrity
  - Throws on verification failure (prevents processing invalid webhooks)
  - Only publishes events that pass cryptographic verification

What customers avoid:

Implementing HMAC signature verification
Managing raw body parsing for signature validation
Writing webhook verification logic
Handling signature timestamp validation
Building replay attack protection

2. Secure Secret Retrieval with Fallback

Flexible secret management with multiple resolution strategies:


Secret resolution logic:
  - Primary: Direct secret value (stripeWebhookSecret)
  - Fallback: Secret name lookup (stripeWebhookSecretName)
  - Async retrieval from secret management service
  - Error handling with specific error types
  - Configuration validation on startup
 
Error handling:
  - Missing secret → "stripe/bad-config" error
  - Invalid configuration → Fails fast at initialization
  - Secret access failure → Detailed error message

What customers avoid:

Building secret management integration
Implementing secret resolution fallback logic
Writing secret caching mechanisms
Managing secret rotation handling
Coordinating secret access across environments

3. Raw Body Preservation for Signature Validation

Critical request handling for webhook verification:


Webhook controller:
  - @Public() decorator bypasses authentication
  - RawBodyRequest<Request> preserves original request body
  - Extracts stripe-signature header from request
  - Validates body exists before processing
  - Returns specific error for missing body
  - Passes raw buffer to verification service
 
Request validation:
  - Checks for req.rawBody presence
  - Throws "stripe/bad-webhook-request" if missing
  - Provides clear error messaging
  - Prevents processing of incomplete requests

What customers avoid:

Configuring body parser middleware correctly
Preserving raw body alongside parsed body
Managing middleware execution order
Implementing header extraction logic
Writing request validation logic

4. Pub/Sub Event Publishing with Type Wrapping

Seamless event routing to platform event bus:


Event publishing:
  - Wraps native provider events in platform event format
  - Uses buildEvent() for consistent event structure
  - Publishes to dedicated topic (integration-stripe-events)
  - Async publishing with error propagation
  - Logs verification and publishing lifecycle
 
Event structure:
  - StripeEvent class wraps native Stripe.Event
  - Maintains full event payload and metadata
  - Enables type-safe event handling
  - Preserves all provider-specific fields

What customers avoid:

Building pub/sub integration
Writing event transformation logic
Implementing topic naming conventions
Managing event serialization
Coordinating async publishing

5. RxJS Event Type Filtering

Declarative event filtering for downstream consumers:


isStripeEventOfType(type: string):
  - RxJS operator for event type filtering
  - Filters event stream by event.type field
  - Enables declarative saga composition
  - Type-safe event handling in consumers
  - Reduces boilerplate in event handlers
 
Usage in sagas:
  events$.pipe(
    isOfType(StripeEvent),           // Filter by class type
    isStripeEventOfType('customer.subscription.deleted'),  // Filter by event type
    map(({event}) => new Command())  // Transform to command
  )

What customers avoid:

Writing event filtering logic
Implementing type discrimination
Building RxJS operator composition
Managing event stream transformations
Coordinating saga subscriptions

6. Automatic Cloud Function Topic Subscription

Generated subscribers for webhook event consumption:


CloudFunctionGenerator.withPrefix('stripe'):
  - Generates pub/sub topic subscriber functions
  - Auto-wires topic name to function name (onStripeEvent)
  - Deploys as background function triggered by topic
  - Provides structured function exports
  - Enables async event processing
 
Function structure:
  - Topic: integration-stripe-events
  - Function name: stripe-onStripeEvent
  - Async handler with error handling
  - Automatic retry on failure

What customers avoid:

Writing cloud function deployment configuration
Managing topic subscription lifecycle
Implementing function naming conventions
Building retry and error handling
Coordinating function deployment

7. Modular Integration Architecture

Extensible design for multiple third-party service providers:


Module structure:
  - Integration-specific modules (IntegrationStripeModule, future: IntegrationTwilioModule, etc.)
  - Conditional module loading based on configuration
  - Dedicated controllers per integration
  - Isolated services per provider
  - Provider-agnostic base module
 
Configuration:
  - Per-integration options (stripe.stripeApiKey, twilio.apiKey, etc.)
  - Optional integration activation
  - Secret name or value configuration
  - Environment-specific setup
  - Graceful handling of missing integrations
 
Expansion capabilities:
  - Add new integrations without affecting existing ones
  - Consistent patterns for webhook handling across providers
  - Shared infrastructure for all third-party services
  - Business logic isolation per integration

What customers avoid:

Designing extensible integration architecture
Implementing conditional module loading
Writing provider abstraction layers
Managing multi-provider configuration
Building integration registry systems

8. Type-Safe Provider SDK Integration

Seamless integration with third-party service SDKs:


Service integrations (current: Stripe, future: others):
  - Wraps official provider SDKs
  - Provides dependency injection via service tokens
  - Exposes SDK-specific functionality (stripe.webhooks.constructEvent(), etc.)
  - Maintains full type safety with provider event types
  - Enables testing with SDK mocking
 
SDK features leveraged:
  - Webhook signature verification
  - Event structure validation
  - Type definitions for all event types
  - Automatic timestamp tolerance checking
  - Built-in error handling
  - Provider-specific business logic methods

What customers avoid:

Writing webhook verification from scratch
Implementing timestamp tolerance logic
Managing SDK version compatibility
Building provider-specific type definitions
Testing webhook verification logic

9. Comprehensive Error Handling with Typed Errors

Structured error responses for all failure modes:


Error types:
  - {provider}/bad-webhook-request → Missing request body
  - {provider}/bad-config → Missing or invalid secret configuration
  - Provider SDK errors → Signature verification failures
  - Integration-specific business logic errors
 
Error handling flow:
  - Request validation errors → 400 Bad Request
  - Configuration errors → Server startup failure
  - Verification errors → 400 Bad Request with details
  - Publishing errors → Propagated to caller
  - Business logic errors → Logged and handled gracefully

What customers avoid:

Designing error taxonomy
Implementing error type discrimination
Writing error response formatting
Managing error logging
Building error documentation

10. Logging and Observability

Detailed event lifecycle logging:


Logging points:
  - "Stripe Event Received" → Initial webhook receipt
  - "Stripe Event Verified" → Successful signature verification (includes event ID and type)
  - "Stripe Event Successfully Published" → Pub/sub publishing complete
  - Debug level for detailed event inspection
 
Logged metadata:
  - Event ID for tracing
  - Event type for filtering
  - Verification status
  - Publishing status

What customers avoid:

Implementing structured logging
Writing log aggregation logic
Building event tracing
Managing log levels
Correlating webhook lifecycle

🤖 This documentation was generated using AI and human-proofed for accuracy.

Integration Service

On This Page

What It Does

Key Capabilities

How It Fits Together

Common Use Cases

Current (Payment/Stripe Integrations)

Future Expansion Possibilities

What You Don’t Have to Build

Technical Details

Heavy-Lifting Features

1. Cryptographic Webhook Verification

2. Secure Secret Retrieval with Fallback

3. Raw Body Preservation for Signature Validation

4. Pub/Sub Event Publishing with Type Wrapping

5. RxJS Event Type Filtering

6. Automatic Cloud Function Topic Subscription

7. Modular Integration Architecture

8. Type-Safe Provider SDK Integration

9. Comprehensive Error Handling with Typed Errors

10. Logging and Observability