A cached or static storefront is fast until the catalog changes. minipim tells your site the moment something changes — from the admin, a connector, an API script or an AI agent — so you can revalidate just the affected pages.

1. Add a webhook endpoint

Create a route in your storefront, for example POST /api/minipim. It must be reachable over public https; private and local addresses are refused.

2. Subscribe

In the admin, go to Connectors and install the Headless connector with:

  • the destination URL of your route;
  • a secret of at least 16 random characters — store the same value in your site’s environment;
  • the events you want. The defaults cover products, variants, categories, brands, content pages, media, modifiers and related products. You can use exact names (product.updated) or patterns (product.*).

3. Verify, then revalidate

Every delivery carries an X-MiniPim-Signature-256 header: sha256= plus an HMAC-SHA256 of the raw body. Verify it against the raw body, before parsing:

import { verifyMinipimWebhook } from '@minipim/sdk/webhook';

export async function POST(req: Request) {
  const rawBody = await req.text();
  const ok = verifyMinipimWebhook({
    rawBody,
    signature: req.headers.get('x-minipim-signature-256') ?? '',
    secret: process.env.MINIPIM_WEBHOOK_SECRET!,
  });
  if (!ok) return new Response('invalid signature', { status: 401 });

  const event = JSON.parse(rawBody);
  // event = { name, organization_id, entity_id, actor, timestamp, payload }
  await revalidateFor(event.name, event.entity_id);
  return new Response('ok');
}

On edge runtimes use verifyMinipimWebhookEdge from @minipim/sdk/webhook-edge (it’s async).

Payloads are deliberately thin — product.updated says which fields changed, not their new values. Use entity_id to work out which pages to revalidate, and fetch fresh data from the API when you rebuild them.

4. Test it

The connector’s page in the admin can send a test event and shows the recent deliveries with their response codes — the quickest way to see whether your endpoint is reachable and your signature check passes.

5. Add a catch-up job

Webhook deliveries are not retried: if your endpoint is down or slow when a change happens, that event is gone. Run a small scheduled job — every few minutes — that asks for anything changed since the last run and revalidates it:

const { data } = await pim.GET('/v1/products', {
  params: { query: { updatedSince: lastRun.toISOString(), limit: 200 } },
});

Webhooks give you speed; the catch-up job gives you correctness.