Webhooks & Callback Processing
Relevant source files
The following files were used as context for generating this wiki page:
The Webhooks & Callback Processing system in FusionOps is primarily handled by the Callback Worker (fusionops-callback-worker), a Cloudflare Worker dedicated to receiving, validating, and storing lead data from external sources. Its main purpose is to act as a reliable ingestion point for lead notifications and callbacks, ensuring data integrity through strict validation and deduplication logic.
This module works in tandem with the API Worker and the Pixel Worker to provide a complete tracking and lead management lifecycle. It utilizes a dedicated Cloudflare D1 database instance, fusionops-callback-new-v2, for persisting received lead information and tracking processed claims.
Sources: CLAUDE.md, INFRASTRUCTURE_SETUP.md, DEPLOYMENT_SUMMARY.md
Architecture and Data Flow
The Callback Worker is built on the Hono framework and deployed as a Cloudflare Worker. It is designed for high performance (14ms startup time) and minimal footprint. The system architecture follows a linear pipeline: request ingestion, security headers application, deduplication check, schema validation, and database persistence.
The following diagram illustrates the request flow for a standard callback:
The system ensures that every incoming request is processed within a specific time budget and that all interactions with the D1 database are parameterized to prevent injection attacks.
Sources: apps/worker/src/index.ts:1-25, DEPLOYMENT_SUMMARY.md, SECURITY_AUDIT_DEEP.md
Key Components
1. Callback Handler
The primary entry point for POST requests to /callback. This handler orchestrates the validation and storage logic. It expects a JSON payload containing lead details, affiliate information, and unique identifiers (like lead_id or click_id).
| Feature | Implementation |
|---|---|
| Endpoint | POST /callback |
| Database | fusionops-callback-new-v2 |
| Response | JSON status object |
Sources: apps/worker/src/handlers/callback.ts, INFRASTRUCTURE_SETUP.md
2. Deduplication Engine
To prevent redundant processing of the same webhook notification (which often happens with retries from external providers), the system implements a deduplication layer. It uses the Deduplicator class to check if a specific claim_id has already been processed within a sliding window.
3. Validation Logic
Incoming data must conform to predefined schemas. This is handled by a validation library that checks for required fields such as amount, currency, and status.
Sources: apps/worker/src/lib/validation.ts
Security & Anti-Fingerprinting
The Callback Worker implements specific security measures to protect the infrastructure and prevent fingerprinting by external entities (like Google or ad networks).
Response Header Randomization
To avoid identical response patterns across multiple domains, the worker is being updated to inject domain-specific variations in headers and include random timing delays.
| Security Feature | Purpose |
|---|---|
| CORS Restriction | Restricts access to trusted origins and domains. |
| User-Agent Variation | Uses randomized User-Agents when forwarding to Voluum. |
| Timing Jitter | Adds 0-10ms random delays to mask processing patterns. |
| Masked Errors | Prevents leaking infrastructure details in error responses. |
Sources: SECURITY_AUDIT_DEEP.md:10-45, apps/worker/src/index.ts:30-40
Database Schema
The fusionops-callback-new-v2 database contains tables for managing received data and idempotency.
Claims Table
Used for tracking processed webhook IDs to ensure idempotency.
| Field | Type | Description |
|---|---|---|
| id | TEXT (PK) | Unique identifier for the webhook/claim. |
| processed_at | TIMESTAMP | When the claim was first handled. |
| payload_hash | TEXT | Hash of the data to detect payload changes. |
Sources: INFRASTRUCTURE_SETUP.md:60-75, apps/worker/src/lib/dedup.ts
Conclusion
The Webhooks & Callback Processing system provides a hardened, idempotent gateway for external lead data. By separating callback handling into a dedicated worker and database, FusionOps ensures that high-volume lead notifications do not impact the performance of the main API worker while maintaining a strict audit trail of all processed claims. Significance is placed on preventing infrastructure correlation through header randomization and timing jitter, vital for maintaining the longevity of the associated ad accounts.
Sources: SECURITY_AUDIT_DEEP.md, DEPLOYMENT_SUMMARY.md