PostbackHandler Service

Overview

The PostbackHandler is a sophisticated Azure Function microservice that processes various types of postback pixels and revenue events from multiple advertising platforms. This service acts as a central hub for handling conversion tracking, revenue attribution, and pixel firing across different advertising networks including Facebook, Snapchat, TikTok, and custom postback systems.

Business Purpose

This service serves as a critical component in the advertising ecosystem that: - Processes postback pixels from various advertising platforms (Facebook, Snapchat, TikTok) - Handles conversion tracking and revenue attribution events - Manages pixel firing for different monetization events - Integrates with campaign data to enrich event information - Routes processed events to appropriate downstream systems via Event Hubs - Supports both real-time event processing and test event simulation

Architecture

Service Type

Platform: Azure Functions (Containerized Kubernetes Microservice)
Runtime: Node.js
Trigger: HTTP Trigger (Anonymous authentication)
Pattern: Event-Driven Pixel Processing with Multi-Platform Integration

Key Components

graph TD
    A[HTTP Request] --> B[PostbackHandler]
    B --> C{Event Source?}

    C -->|Event Hub| D[Dispatched Events]
    C -->|Direct HTTP| E[Test Events]

    D --> F[Event Processing]
    E --> G[Test Message Generation]
    G --> F

    F --> H[Campaign Resolution]
    H --> I{Campaign Found?}

    I -->|No| J[Router Result Service]
    J --> K[Blob Storage]
    K --> L[Campaign Data]
    L --> M[Cache Campaign]

    I -->|Yes| N[Pixel Type Resolution]
    M --> N

    N --> O[Pixel Processing]
    O --> P{Pixel Type?}

    P -->|Conversion| Q[Conversion Events]
    P -->|Revenue| R[Revenue Events]
    P -->|Initialize| S[Router Events]
    P -->|Session| T[Session Events]

    Q --> U[Event Hub: conversions]
    R --> V[Event Hub: publisherrevenue]
    S --> W[Event Hub: routerresult]
    T --> X[Event Hub: routerresult]

    Y[Redis Cache] --> F
    Z[Cosmos DB] --> H
    AA[Document Cache] --> H

Supported Pixel Types

Conversion Pixels

PostbackGETConversion: GET-based conversion tracking
PostbackPOSTConversion: POST-based conversion tracking
FacebookConversion: Facebook conversion API integration
SnapchatConversion: Snapchat conversion tracking
TikTokConversion: TikTok conversion tracking

Revenue Pixels

PostbackGETPayout: GET-based revenue tracking
PostbackPOSTPayout: POST-based revenue tracking
FacebookRevenue: Facebook revenue attribution
SnapchatRevenue: Snapchat revenue tracking
TikTokRevenue: TikTok revenue attribution
QwRevenueGET/POST: QuoteWizard revenue events

Initialization Pixels

PostbackGETInitialize: GET-based session initialization
PostbackPOSTInitialize: POST-based session initialization
SessionAdPixel: Session-based ad pixel tracking

Data Flow

Event Processing Pipeline

Event Reception: Receives events via HTTP (direct or Event Hub dispatched)
Event Classification: Determines if event is test or production
Campaign Resolution: Resolves campaign ID from event data or router results
Pixel Type Mapping: Maps event to appropriate pixel type and destination
Event Enrichment: Adds metadata, session data, and tracking information
Pixel Firing: Executes pixel firing logic based on type
Event Routing: Routes processed events to appropriate Event Hubs

Event Structure

Input Event Format

{
    "wizsid": "session-id",
    "campaignKey": "campaign-id",
    "eventType": "conversion|revenue|initialize",
    "externalIdentifier": "external-transaction-id",
    "data": {
        "sessiontrackid": "session-track-id",
        "campaignkey": "campaign-key"
    },
    "testEvent": false
}

Output Event Format

{
    "recordid": "generated-32-char-id",
    "serviceName": "PostbackHandler",
    "eventhub": "target-eventhub",
    "wizsid": "session-id",
    "campaignKey": "campaign-id",
    "monetizationEvent": "event-type",
    "externalIdentifier": "external-id",
    "processStatus": "success|error-message",
    "testEvent": false
}

Core Functionality

Campaign Resolution

Direct Campaign ID: Uses campaign ID from event data if available
Router Result Lookup: Queries router results from blob storage if campaign ID missing
Cache Integration: Leverages Redis cache for performance optimization
Fallback Handling: Graceful handling when campaign cannot be resolved

Pixel Processing

Type-Based Routing: Routes events to appropriate Event Hubs based on pixel type
Platform Integration: Handles platform-specific pixel requirements
Test Mode Support: Supports test event processing with disabled pixel firing
Error Handling: Comprehensive error handling with failed event tracking

Key Features

Multi-Platform Support: Handles pixels from Facebook, Snapchat, TikTok, and custom systems
Flexible Event Routing: Dynamic Event Hub routing based on pixel type
Test Environment: Supports test event generation and processing
Caching Strategy: Redis caching for improved performance
Session Management: Session-based tracking and data enrichment
Revenue Attribution: Accurate revenue tracking across multiple channels

Event Hub Integration

Output Destinations

conversions: Conversion tracking events
publisherrevenue: Revenue attribution events
unaccountedrevenue: Unaccounted revenue events
exchangerevenue: Exchange revenue events
routerresult: Router and initialization events
pixel_result: Pixel processing results
revenueevents: QuoteWizard revenue events
unauditedrevenue: Unaudited revenue events

Event Routing Logic

Events are routed to different Event Hubs based on: - Pixel type configuration - Revenue attribution rules - Platform-specific requirements - Event classification (conversion vs revenue)

Dependencies

External Services

Redis Cache: Session and campaign data caching
Azure Blob Storage: Router result storage
Cosmos DB: Campaign and document data
Event Hubs: Event routing and downstream processing
Platform APIs: Facebook, Snapchat, TikTok integration

Key NPM Packages

@azure/cosmos: Cosmos DB integration
@azure/storage-blob: Blob storage operations
@redis/client: Redis caching
axios: HTTP client for external API calls
lodash: Data manipulation utilities
moment: Date/time handling
uuid: Unique identifier generation

Configuration

Environment-Specific Settings

Development: Test endpoints and development caches
Integration: Integration testing with staging platforms
Production: Production APIs and live pixel firing

Pixel Type Configuration

The service uses PixelTypes.js to define: - Supported pixel types and their actions (GET/POST) - Target Event Hub mappings - Platform-specific settings - Revenue attribution rules

Performance Characteristics

Processing Metrics

Throughput: ~500 events per second
Latency: <300ms average processing time
Cache Hit Rate: ~85% for campaign resolution
Success Rate: 99.5% event processing success

Scalability Features

Concurrent Processing: Parallel event processing
Redis Caching: Reduced database load
Event Hub Partitioning: Distributed event processing
Stateless Design: Horizontal scaling capability

Error Handling

Error Scenarios

Missing Campaign ID: Unable to resolve campaign from event data
Invalid Pixel Type: Unsupported or malformed pixel type
Platform API Failures: External platform integration errors
Cache Failures: Redis connection or operation failures

Failed Event Management

Failed events are collected and returned for retry processing
Detailed error logging for debugging and monitoring
Graceful degradation when external services are unavailable

Security Considerations

Anonymous HTTP Trigger: Internal service with no external authentication
Data Privacy: Secure handling of user session and revenue data
Platform Integration: Secure API integration with advertising platforms
Audit Trail: Comprehensive logging for compliance and debugging

Monitoring and Observability

Logging

Structured logging with configurable levels
Event processing traces and performance metrics
Platform integration success/failure rates
Cache performance and hit rates

Metrics

Event processing throughput and latency
Pixel firing success rates by platform
Campaign resolution success rates
Error rates and retry statistics

This service integrates with the broader Publisher ecosystem: - RouterV2: Provides router results for campaign resolution - DocumentCacheHandler: Provides cached campaign data - Revenue Services: Consume revenue attribution events - Analytics Services: Use conversion and revenue data - Platform APIs: Facebook, Snapchat, TikTok integration

Troubleshooting

Common Issues

Campaign Resolution Failures: Check router result availability and cache status
Pixel Firing Errors: Verify platform API connectivity and credentials
Performance Issues: Monitor cache hit rates and Event Hub throughput
Event Routing Problems: Review pixel type configuration and Event Hub mappings

Debug Steps

Check Application Insights for event processing traces
Verify Redis cache connectivity and performance
Review platform API response codes and error messages
Monitor Event Hub message flow and partition health

Development

Local Development Setup

Clone repository
Install dependencies: npm install
Configure Redis connection
Set up Cosmos DB and Blob Storage connections
Configure Event Hub connection strings
Set up platform API credentials
Run tests: npm test

Code Structure

src/Handler.js: Main event processing logic
src/PixelTypes.js: Pixel type definitions and routing
src/RouterResultService.js: Campaign resolution logic
src/CacheService.js: Redis caching operations
src/DocumentCacheService.js: Document cache integration
config/: Environment-specific configurations