A webhook is just a signal
Every event ends in the same operation: rebuild the product record from current API data. Duplicates and out-of-order events can't corrupt the index.
case study · integration
Fast, Algolia-powered product search for a store on the Shoper platform, which has no off-the-shelf integration. A custom sync service, search-as-you-type suggestions and a filterable results page, embedded in the store theme with a single file.
01 / challenge
The store needed search that forgives typos, knows synonyms, shows results while typing and lets shoppers filter like in big stores. Shoper has no Algolia integration, so everything had to be built: from pulling the catalogue via the REST API to a component embedded in the theme. On top of that, part of the API's behaviour isn't covered by the public documentation.
02 / principles
The work followed Spec-Driven Development: the specification was approved before the first line of code, and every phase ended with a summary and a commit. Every claim about the Shoper API had a status in the spec, and assumptions became facts only after being checked against real responses.
Every event ends in the same operation: rebuild the product record from current API data. Duplicates and out-of-order events can't corrupt the index.
The frontend only gets a search-only key. The build fails if anything resembling an admin key shows up in the bundle.
Order webhooks carry personal data. The service stores nothing but IDs, and Algolia analytics only starts after the shopper's consent.
Atomic index swaps, a guard against wiping the index and a fallback to Shoper's native search if Algolia fails. One flag switches the integration off.
03 / architecture
A sync service in a single container receives webhooks, queues them and refreshes products. Every 20 minutes it pulls changes by modification date, and once a day it compares the whole catalogue with the index and fixes any drift. The browser talks to Algolia directly.
04 / delivered
05 / result
Screenshots from a real store on the Storefront theme with a demo catalogue. Click a screenshot to enlarge it.


06 / what the real API showed
Verification against a live store and live Algolia caught behaviour that, if coded “from memory”, would have ended in silent bugs in production.
| Area | What we found | Solution |
|---|---|---|
| Shoper pagination | A page size above 50 silently falls back to 10. | The client always requests at most 50. |
| API limits | A 429 response comes back as HTML, without Retry-After. | Throttling based on X-Shop-Api-* headers and a custom backoff. |
| API filters | Unknown filter syntax is ignored and returns the whole catalogue. | Every syntax is checked by a “future date returns 0 results” test. |
| Webhooks | X-Webhook-Id identifies the configuration, not the delivery; events can arrive together a minute later. | Content-based deduplication and idempotent refresh from the API. |
| Deleted order | Its items can no longer be fetched from the API, and stock is restored without changing the modification date. | Product IDs taken from the webhook payload, with the daily reconciliation as a fallback. |
| Index swap | The atomic swap in the Algolia SDK hangs when the index doesn't exist yet. | The first import writes directly; later ones swap with a timeout. |
| Algolia connection | The SDK doesn't fail over to backup hosts on a DNS error. | Custom retries for connection errors. |
| Storefront theme | Consent is handled by a different API than in the older theme, and the store runs a Service Worker. | Integration with the Storefront consent module and versioned script URLs. |
07 / metrics
deferThe metrics come from a test environment: a Shoper store (Storefront) with an 80-product demo catalogue and an Algolia app on the free plan. They are not the client's business data. Impact on conversion and zero-result searches is measured in Algolia Analytics after going live.
08 / process
stack
next steps
What remains before production are business decisions: the Algolia plan, the synonym list, the analytics scope and the availability rule. The architecture is ready for what comes next: recommendations, personalisation, blog content search and indices for more languages.
next step
Tell me what you want to achieve. I'll come back with a concrete proposal, a quote and a delivery plan.