Sync Architecture

This page explains how Fulfiro keeps data synchronized with WooCommerce at a technical level.

Three sync layers

Layer 1: Webhooks (real-time, event-driven)

WooCommerce sends HTTP POST requests to Fulfiro's webhook endpoint when products or orders change. Each webhook includes an HMAC-SHA256 signature verified against a shared secret. The endpoint returns 200 immediately, then enqueues the payload for async processing via BullMQ (backed by Redis). This prevents WooCommerce timeouts from blocking the webhook delivery.

Layer 2: Scheduled delta sync (background, periodic)

A cron job runs every 15 minutes and checks each store's last sync timestamp. It fetches only products modified since that timestamp (modified_after parameter on the WooCommerce REST API). This catches anything webhooks might have missed -- server restarts, dropped connections, or webhook delivery failures.

Layer 3: Full manual sync (user-triggered)

Users can trigger a full resync from the store settings page. This re-imports all products regardless of modification date. Used after bulk changes or as a recovery mechanism.

Queue processing

All sync operations (webhook payloads, delta sync results, stock pushes) flow through BullMQ queues. Workers process jobs with configurable concurrency. Failed jobs are retried with exponential backoff (up to 5 retries). Dead-letter queues capture jobs that exhaust retries for investigation.

Outbound pushes

When stock changes in Fulfiro, the new available quantity is pushed to WooCommerce via the REST API. Batch operations use the WooCommerce batch endpoint (up to 100 products per request). Pushes also go through BullMQ with retry logic.

Circuit breaker

If a store experiences repeated API failures, a circuit breaker temporarily pauses sync to prevent cascading load on a failing WooCommerce server. The breaker resets automatically after a cooldown period.

Related: Idempotency | Stock Consistency | WooCommerce Sync