Webhooks

Real-time product tracking using webhooks for instant inventory updates.

Overview

Webhooks provide real-time notifications when products or variants are created, updated, or deleted on your e-commerce platforms. This eliminates the need to query the CMS for every inventory sync, significantly improving performance.

Benefits

• Real-time Tracking: Products are tracked immediately when created/updated
• Reduced Load: No need to fetch all products on every sync
• Faster Syncs: Only products in the database need inventory updates
• Scalability: Handles high-volume stores efficiently

Supported Platforms

BigCommerce

• Product created
• Product updated
• Product deleted
• Product inventory updated
• Variant created
• Variant updated
• Variant deleted

WooCommerce

• Product created
• Product updated
• Product deleted
• Product restored
• Variation created
• Variation updated
• Variation deleted

Setup

BigCommerce

1. Generate Webhook Secret

   • Navigate to BigCommerce admin
   • Go to Advanced Settings > Webhooks
   • Click Create a Webhook
   • Generate a secure secret key

2. Configure in GSM Middleware

   • Go to GSM Middleware > Control Panel
   • Edit the BigCommerce site
   • Enter the webhook secret in Webhook Secret field
   • Click Save

3. Create Webhooks in BigCommerce

   Create webhooks for these scopes:

   • store/product/*
   • store/product/inventory/updated

   Set destination URL:

   https://your-wordpress-site.com/wp-json/gsm-middleware/v1/webhooks/products/{SITE_ID}

   Replace {SITE_ID} with your site's ID from the control panel.

4. Test Webhook

   • Use BigCommerce's "Test" button
   • Check GSM Middleware > Queue Statistics for received webhook
   • Verify product appears in rm_items table

WooCommerce

Coming Soon

WooCommerce webhook setup will be available in a future update. Currently, WooCommerce sites rely on scheduled full syncs.

How Webhooks Work

Flow Diagram

┌─────────────────────┐
│  Product Created    │
│  on Storefront      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────────────┐
│  CMS Sends Webhook          │
│  POST /webhooks/products/5  │
└──────────┬──────────────────┘
           │
           ▼
┌──────────────────────────────────┐
│  GSM Middleware Receives         │
│  1. Verify signature (HMAC)      │
│  2. Check for duplicates         │
│  3. Log to rm_webhook_log        │
│  4. Queue processing job         │
│  5. Return 200 OK (< 500ms)      │
└──────────┬───────────────────────┘
           │
           ▼
┌──────────────────────────────────┐
│  Queue Processor (every 5 min)   │
│  1. Dequeue webhook job          │
│  2. Extract product data         │
│  3. Update rm_items table        │
│  4. Mark webhook processed       │
└──────────────────────────────────┘

Signature Verification

BigCommerce webhooks are signed using HMAC-SHA256. The signature is verified on receipt:

// Signature header: X-BC-Webhook-Signature
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_BC_WEBHOOK_SIGNATURE'];
$secret = 'your-webhook-secret';

$expected = hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Valid webhook
} else {
    // Invalid - reject
}

Webhook Logging

All webhooks are logged to rm_webhook_log table for tracking and debugging.

Log Fields

• id: Unique log ID
• site_id: Site that received webhook
• event_type: Event type (e.g., store/product/created)
• payload: Full webhook payload (JSON)
• payload_hash: SHA256 hash for deduplication
• headers: HTTP headers
• signature_valid: Whether signature verification passed
• status: queued, processing, processed, or failed
• attempts: Number of processing attempts
• error_message: Error message if failed
• queue_job_id: Linked queue job ID
• received_at: Timestamp received
• processed_at: Timestamp processed

Querying Logs

Recent webhooks:

SELECT 
  id,
  site_id,
  event_type,
  signature_valid,
  status,
  received_at
FROM rm_webhook_log
ORDER BY received_at DESC
LIMIT 100;

Failed webhooks:

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

Webhooks for specific site:

SELECT 
  id,
  event_type,
  status,
  received_at
FROM rm_webhook_log
WHERE site_id = 5
ORDER BY received_at DESC
LIMIT 50;

Webhook Statistics

Via REST API

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

Response includes webhook statistics:

{
  "webhooks": {
    "total_24h": 1523,
    "processed": 1498,
    "failed": 25,
    "avg_process_time": "1.2s"
  }
}

Via Database

SELECT 
  COUNT(*) as total,
  SUM(CASE WHEN status = 'processed' THEN 1 ELSE 0 END) as processed,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) as failed,
  SUM(CASE WHEN signature_valid = 1 THEN 1 ELSE 0 END) as valid_signature
FROM rm_webhook_log
WHERE received_at > DATE_SUB(NOW(), INTERVAL 24 HOUR);

Deduplication

Webhooks are deduplicated using a payload hash to prevent duplicate processing.

How It Works

1. Generate SHA256 hash of payload
2. Check if hash exists in last 5 seconds
3. If exists, skip processing and return existing log ID
4. Otherwise, process normally

Example

SELECT 
  id,
  payload_hash,
  received_at
FROM rm_webhook_log
WHERE payload_hash = 'abc123...'
AND received_at > DATE_SUB(NOW(), INTERVAL 5 SECOND);

Error Handling

Automatic Retry

Failed webhooks are automatically retried with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: +2 minutes
• Attempt 3: +4 minutes
• Attempt 4: Marked as failed

Common Errors

Invalid Signature

Error: Invalid signature

• Check webhook secret matches BigCommerce
• Verify secret is entered in site settings
• Ensure secret hasn't changed

Product Not Found

Error: Missing product ID or SKU

• Webhook payload may be malformed
• Check payload in rm_webhook_log
• Report to platform support

Database Error

Error: Failed to insert into rm_items

• Check database connection
• Verify table structure
• Check disk space

Maintenance

Log Cleanup

Webhook logs are automatically cleaned up based on retention period (default: 90 days).

Manual cleanup:

DELETE FROM rm_webhook_log
WHERE received_at < DATE_SUB(NOW(), INTERVAL 90 DAY);

Via WP-CLI:

wp eval "
\$logger = new \GSM\Middleware\Sync\Webhook_Logger(\$wpdb);
echo \$logger->cleanup_old_logs(90) . ' logs deleted';
"

Failed Webhook Alerts

Set up monitoring for failed webhooks:

-- Daily failed webhooks
SELECT 
  site_id,
  COUNT(*) as failed_count
FROM rm_webhook_log
WHERE status = 'failed'
AND received_at > DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY site_id;

Troubleshooting

Webhooks Not Received

1. Check webhook configuration in BigCommerce

   • Verify destination URL is correct
   • Ensure webhook is active
   • Check scope includes product events

2. Test webhook delivery

   • Use BigCommerce test button
   • Check server logs for incoming requests
   • Verify WordPress REST API is accessible

3. Check firewall/security

   • Ensure BigCommerce IPs aren't blocked
   • Verify SSL certificate is valid
   • Check for rate limiting

Signature Validation Failing

1. Verify secret matches

   • Compare secret in GSM settings with BigCommerce
   • Check for extra spaces or characters

2. Check payload format

   • Verify payload is being received correctly
   • Check Content-Type header

3. Review logs

   SELECT payload, headers
   FROM rm_webhook_log
   WHERE signature_valid = 0
   ORDER BY received_at DESC
   LIMIT 10;

Webhooks Queued but Not Processing

1. Check queue processor is running

   wp cron event list | grep gsm_process_queue

2. Verify cron jobs are active

   • Check cron schedule (every 5 minutes)
   • Test manual cron execution

3. Check for stuck jobs

   SELECT *
   FROM rm_queue
   WHERE status = 'processing'
   AND started_at < DATE_SUB(NOW(), INTERVAL 30 MINUTE);

Best Practices

1. Secure Your Webhook Secret

   • Use strong, random secrets
   • Rotate secrets periodically
   • Never commit secrets to version control

2. Monitor Webhook Health

   • Set up alerts for failed webhooks
   • Review logs weekly
   • Track success rates

3. Test Webhook Changes

   • Use BigCommerce test feature
   • Verify in staging first
   • Monitor logs after changes

4. Handle High Volume

   • Webhooks are queued automatically
   • Queue processes every 5 minutes
   • No action needed for high volume

Security

Protection Mechanisms

• Signature Verification: HMAC-SHA256 validation
• Deduplication: Prevent replay attacks (5-second window)
• Rate Limiting: Built into queue system
• Encrypted Storage: Webhook secrets encrypted at rest

Security Checklist

• Webhook secret is strong and random
• Secret is stored encrypted in database
• Signature verification is enabled
• Logs show 100% signature validation
• No secrets in application logs
• HTTPS is enforced for webhook endpoint

Related Documentation

• Queue Management - Understanding the queue system
• Performance Tuning - Optimize for high volume
• API Reference - REST API documentation