Skip to main content

Inventory Sync

Synchronize product inventory from Business Central to all e-commerce platforms with real-time webhooks and scheduled syncs.

Overview​

The Inventory Sync system provides efficient, scalable inventory management across multiple e-commerce platforms (BigCommerce and WooCommerce). It combines webhook-driven real-time updates with scheduled full synchronization to ensure accurate inventory levels.

Key Features​

  • Real-time Updates: Webhook-based product tracking when products are created/updated/deleted
  • Scheduled Sync: Daily overnight full inventory synchronization (2 AM)
  • Custom Queue System: Reliable background job processing with automatic retry
  • Bulk Operations: Efficient batch processing for sites with 20,000+ SKUs
  • Local Product Database: Eliminates redundant CMS queries using rm_items table
  • Signature Verification: Secure webhook authentication (BigCommerce)
  • Comprehensive Logging: Track all webhooks and sync operations

Architecture​

Components​

  1. Queue System (src/Queue/Queue_System.php)

    • Priority-based job execution
    • Exponential backoff retry logic
    • Stuck job detection and recovery

  2. Inventory Sync Classes

    • Base abstract class for shared logic
    • Platform-specific implementations (BigCommerce, WooCommerce)
    • Bulk inventory retrieval from Business Central

  3. Webhook System

    • Product webhook handler for real-time updates
    • Signature verification
    • Fast webhook receipt and background processing

  4. Cron Jobs

    • Daily full sync (2 AM)
    • Queue processor (every 5 minutes)
    • Maintenance and cleanup

How It Works​

Full Inventory Sync (Daily)​

┌─────────────────┐
│  Cron (2 AM)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Queue Jobs     │  ← One job per active site
└────────┬────────┘
         │
         ▼ (Processed every 5 min)
┌─────────────────────────────────┐
│  For Each Site:                 │
│  1. Get products from CMS       │
│  2. Extract SKUs                │
│  3. Query Business Central      │
│  4. Update CMS inventory        │
│  5. Update rm_items table       │
└─────────────────────────────────┘

Webhook Sync (Real-time)​

┌──────────────────┐
│ Product Created/ │
│ Updated/Deleted  │
└────────┬─────────┘
         │
         ▼
┌─────────────────────┐
│ Webhook Received    │
│ - Verify signature  │
│ - Log to DB         │
│ - Queue job         │
│ - Return 200 OK     │
└────────┬────────────┘
         │
         ▼ (Processed every 5 min)
┌─────────────────────┐
│ Update rm_items     │
│ - Add product       │
│ - Update SKU        │
│ - Deactivate        │
└─────────────────────┘

Manual Triggers​

Via REST API​

Trigger inventory sync for a specific site:

curl -X POST \
  'https://your-site.com/wp-json/gsm-middleware/v1/inventory/sync/5' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Trigger sync for all active sites:

curl -X POST \
  'https://your-site.com/wp-json/gsm-middleware/v1/inventory/sync/all' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Get sync statistics:

curl -X GET \
  'https://your-site.com/wp-json/gsm-middleware/v1/inventory/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Via Control Panel​

  1. Navigate to GSM Middleware > Control Panel
  2. Select the site you want to sync
  3. Click Sync Inventory button
  4. Monitor progress in the queue statistics

Configuration​

Global Settings​

Navigate to GSM Middleware > Settings:

  • Webhook Log Retention: 1-365 days (default: 90)
    • Controls automatic cleanup of webhook logs
    • Older logs are deleted daily at 3 AM

Per-Site Settings​

In the site edit modal:

  • Webhook Secret: BigCommerce webhook signature secret (encrypted)
    • Required for webhook signature verification
    • Automatically verified on each webhook receipt

Database Tables​

rm_queue​

Stores all queued jobs for background processing.

rm_webhook_log​

Logs all incoming webhooks for tracking and debugging.

rm_items​

Central inventory table tracking all products across all sites.

Performance​

Optimizations​

  • Batch Processing: Database updates in batches of 500 records
  • Efficient API Calls: Pagination and chunking for large catalogs
  • Channel Filtering: Only processes products in assigned channels (BigCommerce)
  • SKU Cleaning: Normalizes SKUs to Business Central format (20 char limit)
  • Deduplication: Prevents duplicate webhook processing (5-second window)

Expected Performance​

  • Sites with 1,000 SKUs: ~1-2 minutes per sync
  • Sites with 10,000 SKUs: ~5-10 minutes per sync
  • Sites with 20,000+ SKUs: ~10-20 minutes per sync

Monitoring​

Queue Statistics​

Check queue status via REST API:

curl -X GET \
  'https://your-site.com/wp-json/gsm-middleware/v1/inventory/stats'

Response:

{
  "queue": {
    "total": 150,
    "pending": 5,
    "processing": 2,
    "completed": 140,
    "failed": 3
  },
  "last_syncs": [
    {
      "site_id": "5",
      "last_sync": "2026-03-19 02:15:23"
    }
  ]
}

Failed Webhooks​

Failed webhooks are automatically logged in rm_webhook_log with error messages. Review via database query:

SELECT 
  id, 
  site_id, 
  event_type, 
  error_message, 
  received_at,
  attempts
FROM rm_webhook_log 
WHERE status = 'failed' 
ORDER BY received_at DESC 
LIMIT 100;

Troubleshooting​

Inventory Not Updating​

  1. Check site is active: Verify in Control Panel
  2. Verify cron is running: Check gsm_process_queue is scheduled
  3. Check API credentials: Test connection in site settings
  4. Review webhook logs: Look for signature validation failures
  5. Check queue: Ensure jobs aren't stuck

Webhooks Not Processing​

  1. Verify webhook secret: Check it matches BigCommerce webhook configuration
  2. Check signature validation: Review rm_webhook_log for validation errors
  3. Test webhook manually: Use BigCommerce webhook test feature
  4. Check queue processor: Ensure cron job is running every 5 minutes

Queue Jobs Stuck​

The system automatically releases stuck jobs after 30 minutes. To manually release:

# Via WP-CLI
wp eval "
\$queue = new \GSM\Middleware\Queue\Queue_System(\$wpdb);
echo \$queue->release_stuck_jobs(30) . ' jobs released';
"