Skip to main content

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​

Read more about the webhook system here.

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

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).

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.
Last updated on