Caching

The Storefront API offers a sophisticated caching system for fast, real-time data delivery. Understanding how caching works is essential for building high-performance storefronts and implementing effective cache invalidation strategies.

Why caching matters

Properly implemented caching is critical for storefront performance because:

• Speed: Cached data is served instantly without re-computing or re-querying the database.
• Scalability: Reduces load on backend systems, allowing you to serve more concurrent shoppers.
• Reliability: If a cache update fails, the existing cache serves stale data instead of returning errors.

Cached data types

The following data types are automatically cached and available through the Storefront API:

Configuration data

• Markets
• Pricelists
• Languages

Product catalog data

• DisplayItems
• Categories
• Brands
• Collections
• Affiliates
• BrickAndMortars

Cache invalidation

Cache invalidation happens through two distinct mechanisms, each with different characteristics.

Delta updates

A delta update refreshes only the parts of the cache that changed. It's fast and uses webhooks for notification.

When it happens

• Real-time: Within seconds of changes in Centra.
• Automatic: No manual intervention needed.
• Event-driven: Triggered by specific data changes.

Important characteristics

• Webhooks enabled: Notifications sent via webhooks after cache updates.
• Selective update: Only changed data is refreshed.
• Fast: Typically completes in seconds.
• No guaranteed order: Multiple events may arrive out of sequence.

When to use

• Real-time updates to your storefront.
• Immediate reflection of price changes, inventory, etc.
• Notifying systems that depend on Centra data.

Full cache rebuild

A full cache rebuild refreshes all data in both cache layers at once. It's comprehensive but heavyweight.

When it happens

Manually, operations teams can trigger a rebuild.

What happens during rebuild

1. All sync services execute in a fixed sequence.
2. Configuration data is updated.
3. Product catalog data is updated.
4. Takes seconds to minutes depending on catalog size.
5. During rebuild, existing cache remains available.

Important characteristics

• No webhooks fired: Full rebuilds don't trigger webhook notifications.
• Complete refresh: All data refreshed regardless of changes.
• Slow but reliable: Guarantees cache consistency but slower than incremental.
• Recovery mechanism: Always available as fallback if incremental updates fail.

When to use

• Recovery from suspected cache corruption.
• When incremental updates fall behind.

important

A full cache rebuild should be followed by a similar operation on dependant systems. This includes any cache maintained by a front-end proxy, as well as catalog exports to e.g. merchandising services.

Webhook system

Webhooks are requests sent to your endpoint when cache updates complete. They allow your systems to know exactly what changed without polling.

Webhook delivery

When cache updates complete after incremental changes, the system sends HTTP POST requests to your configured webhook endpoints.

Request format

X-Centra-Signature: v1,t=1699999999,hmac-sha256=abc123...

{
  "DisplayItems": ["101", "102", "103"],
  "Brands": ["5"],
  "Pricelists": ["11"]
}

What each part means

• X-Centra-Signature: Request header, a HMAC signature.
• Payload: Request body, a JSON string with affected data type IDs.

Webhook payload structure

The payload is a JSON object where:

• Keys: Data types that changed.
• Values: Arrays of IDs that were affected, as strings.

Important webhook behaviors

• Not guaranteed in order - Webhooks may arrive out of sequence. Handle duplicate/old data gracefully.
• Not guaranteed to arrive - Network issues may prevent delivery. Always have a fallback mechanism.
• May be duplicated - The same event might trigger multiple webhooks. Use idempotent processing.
• Fire after cache updates - Your API will return updated data immediately when you query it.
• Large payloads chunked - If many IDs changed, payload is split into multiple HTTP requests.
• Async delivery - Webhooks don't block cache updates. Delivery may take a few seconds.

Webhook type groups

The following top-level keys can appear in webhook payloads:

Key	Meaning
DisplayItems	Product variants that changed
Categories	Categories that changed
Brands	Brands that changed
Markets	Markets that changed
Pricelists	Pricelists that changed
Collections	Collections that changed
Languages	Languages that changed
CampaignSites	Campaign sites that changed
Affiliates	Affiliates that changed
BrickAndMortars	Store locations that changed

Webhook triggers

Cache updates are triggered by the following internal event types. The key insight is that some events cascade to multiple data types.

Internal event	Cache invalidated for
AFFILIATE_EVENT	Affiliates
ATTRIBUTE_EVENT	Categories, DisplayItems
BRAND_EVENT	Brands, DisplayItems
BRICK_AND_MORTAR_EVENT	BrickAndMortars
CAMPAIGN_SITE_EVENT	CampaignSites
CATEGORY_EVENT	Categories, DisplayItems
COLLECTION_EVENT	Collections
DISPLAY_EVENT	DisplayItems
DISPLAY_ITEM_EVENT	DisplayItems
DISPLAY_RELATION_EVENT	DisplayItems
DISPLAY_REMOVED_EVENT	DisplayItems
LANGUAGE_EVENT	Languages
LOWEST_PRICE_EVENT	DisplayItems
MARKET_EVENT	DisplayItems, Markets
MARKET_PRODUCTS_EVENT	DisplayItems
MEASUREMENT_CHART_EVENT	DisplayItems
PRICELIST_EVENT	Pricelists
PRODUCT_EVENT	DisplayItems
PRODUCT_MEDIA	DisplayItems
SHIPPING_EVENT	Pricelists
STOCK_EVENT	DisplayItems
STORE_ITEM_EVENT	DisplayItems
VARIANT_EVENT	DisplayItems

info

For events triggering cascading invalidation, it only triggers it for related entities. E.g. ATTRIBUTE_EVENT will trigger invalidation of DisplayItems and Categories where that attribute is exposed.

Webhook security

To ensure webhooks come from Centra, you should verify the signature in the X-Centra-Signature header.

How signature verification works

1. Centra signs each webhook with your shared secret
2. You verify the signature using the same secret
3. If signature is valid, you can trust the webhook is authentic

Signature format: v1,t=TIMESTAMP,hmac-sha256=HASH

Where:

• v1 - Protocol version (always "v1").
• t - Unix timestamp when webhook was sent.
• hmac-sha256 - HMAC-SHA256 hash of the request payload.

Implementation guide

To receive webhooks and keep your storefront cache synchronized, follow these steps.

Step 1: Create a webhook endpoint

Your endpoint must:

• Accept HTTP POST requests.
• Be served over valid HTTPS.
• Be accessible from Centra's infrastructure.
• Process requests within 30 seconds.
• Return HTTP 200 for successful processing.
• Implement idempotent processing (same webhook twice = same result).

Express.js example

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.urlencoded({ extended: false }));

const MAX_TIMESTAMP_AGE_SECONDS = 300;

// Verify webhook signature using regex for clean parsing
function verifyWebhookSignature(payload, signature, secret) {
  // Parse signature: v1,t=TIMESTAMP,hmac-sha256=HASH
  const match = signature.match(/t=(\d+).*hmac-sha256=([a-f0-9]+)/);
  if (!match) {
    throw new Error('Invalid signature format');
  }

  const timestamp = parseInt(match[1], 10);
  const providedHash = match[2];

  // Verify timestamp is recent (prevent replay attacks)
  const now = Math.floor(Date.now() / 1000);
  if (now - timestamp > MAX_TIMESTAMP_AGE_SECONDS) {
    throw new Error('Webhook timestamp too old');
  }

  // Compute expected signature
  const signedContent = `${timestamp}.${payload}`;
  const computedHash = crypto
    .createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');

  // Constant-time comparison (prevents timing attacks)
  if (
    !crypto.timingSafeEqual(
      Buffer.from(providedHash, 'hex'),
      Buffer.from(computedHash, 'hex')
    )
  ) {
    throw new Error('Invalid signature');
  }

  return true;
}

// Middleware: Verify webhook signature
const verifyWebhook = (req, res, next) => {
  const signature = req.headers['x-centra-signature'];

  if (!signature) {
    return res.status(401).json({ error: 'Missing signature' });
  }

  try {
    verifyWebhookSignature(
      req.body.payload,
      signature,
      process.env.CENTRA_WEBHOOK_SECRET
    );
    next();
  } catch (error) {
    console.error('Signature verification failed:', error.message);
    res.status(400).json({ error: 'Invalid webhook' });
  }
};

app.post('/webhook/centra', verifyWebhook, async (req, res) => {
  // Return immediately to Centra
  res.status(200).json({ success: true });

  // Process webhook asynchronously (don't block response)
  processWebhook(req.body.payload).catch(err => {
    console.error('Webhook processing failed:', err);
  });
});

async function processWebhook(payloadString) {
  try {
    const webhookData = JSON.parse(payloadString);

    if (!webhookData || typeof webhookData !== 'object') {
      throw new Error('Invalid webhook data');
    }

    // Iterate over each data type that changed
    for (const [dataType, ids] of Object.entries(webhookData)) {
      if (ids?.length > 0) {
        console.log(`${dataType} changed:`, ids);

        // Invalidate cache for each affected item
        for (const id of ids) {
          // Cache invalidation logic goes here
          // Example: await cache.delete(`${dataType}:${id}`);
        }
      }
    }

    console.log('Webhook processed successfully');
  } catch (error) {
    console.error('Webhook processing error:', error);
  }
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Step 2: Configure webhook in Centra

1. In the Centra admin panel, locate the Storefront API plugin settings.
2. Add your webhook endpoint URL.
3. Optionally set a shared secret for signature verification.
4. Choose which data types to subscribe to (or subscribe to all).
5. Test the webhook (Centra should show success/failure status).

Step 3: Test webhook delivery

1. Trigger a test webhook from the admin panel.
2. Monitor your server logs for the incoming request.
3. Verify signature verification works.
4. Confirm JSON parsing works.
5. Check cache invalidation logic.

Best practices

Caching strategy

• Use webhooks for real-time updates: Webhooks keep your cache fresh within seconds, handling 99% of updates in real-time and providing immediate reflection of price changes, inventory, and product availability.

• Add monitoring and recovery: Detect discrepancies between your cache and source data to identify and recover from any missed updates or inconsistencies.

Security

• Verify webhook signatures: Always verify signatures if configured using constant-time comparison to prevent timing attacks. Check timestamp age to prevent replay attacks, and rotate secrets periodically to minimize exposure if compromised.

• Manage secrets securely: Store webhook secrets in environment variables, never commit them to version control, and use different secrets per environment (dev, staging, prod) to isolate credentials.

Performance

• Avoid blocking on webhook responses: Return HTTP 200 immediately after receiving a webhook, then process the update asynchronously in the background. This ensures Centra's webhook delivery completes quickly.

• Don't refetch all changed data: When a webhook arrives with hundreds or thousands of IDs, avoid refetching all of them immediately. Instead, just invalidate those items from your local cache. Refetch on-demand when the user requests the data.

• Process large webhook payloads in parallel: When webhooks contain many IDs and are split into multiple HTTP requests, process those chunks in parallel rather than sequentially. Each webhook will contain a maximum of 100 events.

• Maintain idempotent processing: Since chunks can arrive out of order or be retried, ensure each chunk can be processed multiple times without causing inconsistent results.

Reliability

• Monitor webhook health with key metrics: Track number of webhooks received, processed, and failed. Record timestamps of last webhook received and successful processing. Expose a health endpoint that reports healthy/degraded status based on time since last successful webhook.

• Implement cache TTL and fallback behavior: If webhooks fail to arrive, implement cache TTL (time-to-live) so that cached data expires automatically. We recommend a SWR (stale-while-revalidate) pattern, serving stale cache while revalidating asynchronously.

Contacting Centra support

Contact Centra support with:

1. Specific symptoms: "Products show old prices".
2. Timing information: "Started happening at 2024-01-15 14:30 UTC".
3. Affected stores/markets: "Store ID 5, all markets".
4. Logs: Webhook delivery logs, error messages, timing info.
5. Reproduction steps: How to trigger the issue.